@provide-io/telemetry 0.2.2

package/dist/slo.js

@@ -0,0 +1,115 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * SLO-oriented telemetry helpers (RED/USE baseline).
+ * Mirrors Python provide.telemetry.slo.
+ */
+import { counter, gauge, histogram, } from './metrics';
+import { getConfig } from './config';
+const _counters = new Map();
+const _histograms = new Map();
+const _gauges = new Map();
+function _lazyCounter(name, description) {
+    let c = _counters.get(name);
+    if (!c) {
+        c = counter(name, { description });
+        _counters.set(name, c);
+    }
+    return c;
+}
+function _lazyHistogram(name, description, unit) {
+    let h = _histograms.get(name);
+    if (!h) {
+        h = histogram(name, { description, unit });
+        _histograms.set(name, h);
+    }
+    return h;
+}
+function _lazyGauge(name, description, unit) {
+    let g = _gauges.get(name);
+    if (!g) {
+        g = gauge(name, { description, unit });
+        _gauges.set(name, g);
+    }
+    return g;
+}
+export function recordRedMetrics(opts) {
+    if (!getConfig().sloEnableRedMetrics)
+        return;
+    const attrs = {
+        route: opts.route,
+        method: opts.method,
+        status_code: String(opts.statusCode),
+    };
+    _lazyCounter('http.requests.total', 'Total HTTP requests').add(1, attrs);
+    if (opts.statusCode >= 500) {
+        // Stryker disable next-line StringLiteral: error counter description is not tested
+        _lazyCounter('http.errors.total', 'Total HTTP errors').add(1, attrs);
+    }
+    _lazyHistogram('http.request.duration_ms', 'HTTP request latency', 'ms').record(opts.durationMs, attrs);
+}
+export function recordUseMetrics(opts) {
+    if (!getConfig().sloEnableUseMetrics)
+        return;
+    const g = _lazyGauge('resource.utilization', 'Resource utilization', opts.unit ?? '%');
+    g.set(opts.utilization, { resource: opts.resource });
+}
+export function classifyError(excName, statusCode) {
+    const isTimeout = statusCode === 0 || excName.toLowerCase().includes('timeout');
+    if (isTimeout) {
+        return {
+            errorType: 'timeout',
+            errorCode: statusCode,
+            errorName: excName,
+            category: 'timeout',
+            severity: 'info',
+            'error.type': excName,
+            'error.category': 'timeout',
+            'error.severity': 'info',
+            'http.status_code': String(statusCode),
+        };
+    }
+    if (statusCode >= 500) {
+        return {
+            errorType: 'server',
+            errorCode: statusCode,
+            errorName: excName,
+            category: 'server_error',
+            severity: 'critical',
+            'error.type': excName,
+            'error.category': 'server_error',
+            'error.severity': 'critical',
+            'http.status_code': String(statusCode),
+        };
+    }
+    if (statusCode >= 400) {
+        const sev = statusCode === 429 ? 'critical' : 'warning';
+        return {
+            errorType: 'client',
+            errorCode: statusCode,
+            errorName: excName,
+            category: 'client_error',
+            severity: sev,
+            'error.type': excName,
+            'error.category': 'client_error',
+            'error.severity': sev,
+            'http.status_code': String(statusCode),
+        };
+    }
+    return {
+        errorType: 'unknown',
+        errorCode: statusCode,
+        errorName: excName,
+        category: 'unknown',
+        severity: 'unknown',
+        'error.type': excName,
+        'error.category': 'unknown',
+        'error.severity': 'unknown',
+        'http.status_code': String(statusCode),
+    };
+}
+export function _resetSloForTests() {
+    _counters.clear();
+    _histograms.clear();
+    _gauges.clear();
+}

package/dist/testing.d.ts

@@ -0,0 +1,10 @@
+/** Reset all telemetry state (config, context, PII rules, health, queues, sampling, resilience, SLO). */
+export declare function resetTelemetryState(): void;
+/** Clear manual trace context (traceId / spanId set via setTraceContext). */
+export declare function resetTraceContext(): void;
+/** Vitest plugin for automatic per-test telemetry isolation. */
+export declare const telemetryTestPlugin: {
+    beforeEach(): void;
+    afterEach(): void;
+};
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAuBA,yGAAyG;AACzG,wBAAgB,mBAAmB,IAAI,IAAI,CAc1C;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED,gEAAgE;AAChE,eAAO,MAAM,mBAAmB;kBAChB,IAAI;iBAIL,IAAI;CAIlB,CAAC"}

package/dist/testing.js

@@ -0,0 +1,51 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Test utilities — reset all telemetry state between tests.
+ * Mirrors Python provide.telemetry.testing.
+ */
+import { _resetConfig } from './config';
+import { _resetContext } from './context';
+import { _resetHealthForTests } from './health';
+import { _resetBackpressureForTests } from './backpressure';
+import { _resetCardinalityForTests } from './cardinality';
+import { _resetSamplingForTests } from './sampling';
+import { _resetResilienceForTests } from './resilience';
+import { resetPiiRulesForTests } from './pii';
+import { _resetSloForTests } from './slo';
+import { _resetPropagationForTests } from './propagation';
+import { _resetRootLogger } from './logger';
+import { _resetOtelLogProviderForTests } from './otel-logs';
+import { _resetTraceContext } from './tracing';
+import { _resetRuntimeForTests } from './runtime';
+/** Reset all telemetry state (config, context, PII rules, health, queues, sampling, resilience, SLO). */
+export function resetTelemetryState() {
+    _resetConfig();
+    _resetContext();
+    _resetHealthForTests();
+    _resetBackpressureForTests();
+    _resetCardinalityForTests();
+    _resetSamplingForTests();
+    _resetResilienceForTests();
+    resetPiiRulesForTests();
+    _resetSloForTests();
+    _resetPropagationForTests();
+    _resetRootLogger();
+    _resetOtelLogProviderForTests();
+    _resetRuntimeForTests();
+}
+/** Clear manual trace context (traceId / spanId set via setTraceContext). */
+export function resetTraceContext() {
+    _resetTraceContext();
+}
+/** Vitest plugin for automatic per-test telemetry isolation. */
+export const telemetryTestPlugin = {
+    beforeEach() {
+        resetTelemetryState();
+        resetTraceContext();
+    },
+    afterEach() {
+        resetTelemetryState();
+        resetTraceContext();
+    },
+};

package/dist/tracing.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Tracing helpers — mirrors Python provide.telemetry @trace decorator and tracer access.
+ *
+ * Uses @opentelemetry/api which provides no-op implementations when no SDK is registered.
+ * withTrace() / @trace work safely without any OTEL setup; they just don't export spans.
+ */
+import { type Tracer } from '@opentelemetry/api';
+/**
+ * Manually inject trace/span IDs (e.g. from an incoming request header).
+ * Returned by getTraceContext(); cleared by _resetTraceContext().
+ */
+export declare function setTraceContext(traceId: string, spanId: string): void;
+/**
+ * Return the current trace context: manual injection first, then active OTEL span.
+ */
+export declare function getTraceContext(): {
+    trace_id?: string;
+    span_id?: string;
+};
+/** Reset manually injected trace context (used in tests). */
+export declare function _resetTraceContext(): void;
+/** Return the tracer for the telemetry library. Noop when no SDK is registered. */
+export declare function getTracer(): Tracer;
+/** Module-level lazy singleton tracer — resolves provider at call time. */
+export declare const tracer: Tracer;
+/**
+ * Return trace_id and span_id from the currently active OTEL span.
+ * Returns an empty object when no span is active or OTEL is not configured.
+ */
+export declare function getActiveTraceIds(): {
+    trace_id?: string;
+    span_id?: string;
+};
+/**
+ * Execute fn inside a new span named `name`.
+ * Works for both sync and async functions.
+ * Mirrors Python @trace decorator behaviour: records exceptions, sets ERROR status.
+ */
+export declare function withTrace<T>(name: string, fn: () => T): T;
+/**
+ * Method/function decorator that wraps the target in withTrace().
+ * Span name defaults to the decorated method name.
+ *
+ * Usage (requires experimentalDecorators: true):
+ *   class Foo {
+ *     @trace('my.operation')
+ *     doWork() { ... }
+ *   }
+ */
+export declare function traceDecorator(name?: string): (_target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor;
+//# sourceMappingURL=tracing.d.ts.map

package/dist/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,MAAM,EAKZ,MAAM,oBAAoB,CAAC;AAW5B;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAGrE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAezE;AAED,6DAA6D;AAC7D,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC;AAED,mFAAmF;AACnF,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,2EAA2E;AAC3E,eAAO,MAAM,MAAM,EAAE,MAAqC,CAAC;AAE3D;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAO3E;AAsED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CA0BzD;AAED;;;;;;;;;GASG;AAEH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,IAExC,SAAS,MAAM,EACf,aAAa,MAAM,GAAG,MAAM,EAC5B,YAAY,kBAAkB,KAC7B,kBAAkB,CAUtB"}

package/dist/tracing.js

@@ -0,0 +1,181 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Tracing helpers — mirrors Python provide.telemetry @trace decorator and tracer access.
+ *
+ * Uses @opentelemetry/api which provides no-op implementations when no SDK is registered.
+ * withTrace() / @trace work safely without any OTEL setup; they just don't export spans.
+ */
+import { SpanStatusCode, trace, context as otelContext, } from '@opentelemetry/api';
+import { getActiveOtelContext } from './propagation';
+import { randomHex } from './hash';
+// Stryker disable next-line StringLiteral: tracer name is not observable without a real SDK
+const TRACER_NAME = '@provide-io/telemetry';
+// ── Manual trace context (injected without an active OTEL span) ───────────────
+let _manualTraceId;
+let _manualSpanId;
+/**
+ * Manually inject trace/span IDs (e.g. from an incoming request header).
+ * Returned by getTraceContext(); cleared by _resetTraceContext().
+ */
+export function setTraceContext(traceId, spanId) {
+    _manualTraceId = traceId;
+    _manualSpanId = spanId;
+}
+/**
+ * Return the current trace context: manual injection first, then active OTEL span.
+ */
+export function getTraceContext() {
+    // Stryker disable next-line ConditionalExpression,LogicalOperator: setTraceContext always sets both; partial state not reachable via public API
+    if (_manualTraceId !== undefined || _manualSpanId !== undefined) {
+        return {
+            // Stryker disable next-line ConditionalExpression: _manualTraceId is always defined here (both set together)
+            ...(_manualTraceId !== undefined && { trace_id: _manualTraceId }),
+            // Stryker disable next-line ConditionalExpression: _manualSpanId is always defined here (both set together)
+            ...(_manualSpanId !== undefined && { span_id: _manualSpanId }),
+        };
+    }
+    const ids = getActiveTraceIds();
+    return {
+        ...(ids.trace_id !== undefined && { trace_id: ids.trace_id }),
+        ...(ids.span_id !== undefined && { span_id: ids.span_id }),
+    };
+}
+/** Reset manually injected trace context (used in tests). */
+export function _resetTraceContext() {
+    _manualTraceId = undefined;
+    _manualSpanId = undefined;
+}
+/** Return the tracer for the telemetry library. Noop when no SDK is registered. */
+export function getTracer() {
+    return trace.getTracer(TRACER_NAME);
+}
+/** Module-level lazy singleton tracer — resolves provider at call time. */
+export const tracer = trace.getTracer(TRACER_NAME);
+/**
+ * Return trace_id and span_id from the currently active OTEL span.
+ * Returns an empty object when no span is active or OTEL is not configured.
+ */
+export function getActiveTraceIds() {
+    const span = trace.getActiveSpan();
+    if (!span)
+        return {};
+    const ctx = span.spanContext();
+    // OTEL no-op spans have all-zero IDs — treat as no active span.
+    if (ctx.traceId === '00000000000000000000000000000000')
+        return {};
+    return { trace_id: ctx.traceId, span_id: ctx.spanId };
+}
+const NOOP_TRACE_ID = '00000000000000000000000000000000';
+/**
+ * Return true if the given span is a no-op (all-zero trace ID).
+ * Used to decide whether to inject synthetic random IDs.
+ */
+function _isNoopSpan(span) {
+    return span.spanContext().traceId === NOOP_TRACE_ID;
+}
+/**
+ * Execute fn with random synthetic trace/span IDs set as manual context,
+ * then restore the previous manual context when done.
+ * Handles both sync and async results.
+ */
+function _withSyntheticIds(fn) {
+    const prevTraceId = _manualTraceId;
+    const prevSpanId = _manualSpanId;
+    // Stryker disable next-line StringLiteral: random IDs are non-deterministic — exact value not observable in mutations
+    setTraceContext(randomHex(16), randomHex(8));
+    const result = fn();
+    if (result instanceof Promise) {
+        return result.then((value) => {
+            _manualTraceId = prevTraceId;
+            _manualSpanId = prevSpanId;
+            return value;
+        }, (err) => {
+            _manualTraceId = prevTraceId;
+            _manualSpanId = prevSpanId;
+            throw err;
+        });
+    }
+    _manualTraceId = prevTraceId;
+    _manualSpanId = prevSpanId;
+    return result;
+}
+/** Shared span handler for withTrace — records exceptions and sets ERROR status. */
+function _spanHandler(fn, span) {
+    try {
+        const result = fn();
+        if (result instanceof Promise) {
+            return result.then((value) => {
+                span.end();
+                return value;
+            }, (err) => {
+                span.recordException(err instanceof Error ? err : new Error(String(err)));
+                span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+                span.end();
+                throw err;
+            });
+        }
+        span.end();
+        return result;
+    }
+    catch (err) {
+        span.recordException(err instanceof Error ? err : new Error(String(err)));
+        span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+        span.end();
+        throw err;
+    }
+}
+/**
+ * Execute fn inside a new span named `name`.
+ * Works for both sync and async functions.
+ * Mirrors Python @trace decorator behaviour: records exceptions, sets ERROR status.
+ */
+export function withTrace(name, fn) {
+    const tracer = trace.getTracer(TRACER_NAME);
+    // If an OTel context was extracted from propagation headers, use it as parent.
+    try {
+        const activeCtx = getActiveOtelContext();
+        if (activeCtx) {
+            return otelContext.with(activeCtx, () => tracer.startActiveSpan(name, (span) => {
+                // Stryker disable next-line ConditionalExpression: noop detection is not observable without SDK — branch outcome equivalent under mutation
+                /* v8 ignore start: noop-span false branch + real-span return are unreachable without a registered OTel provider */
+                if (_isNoopSpan(span))
+                    return _withSyntheticIds(() => _spanHandler(fn, span));
+                return _spanHandler(fn, span);
+                /* v8 ignore stop */
+            }));
+        }
+    }
+    catch {
+        // Graceful degradation — fall through to default behaviour.
+    }
+    return tracer.startActiveSpan(name, (span) => {
+        // Stryker disable next-line ConditionalExpression: noop detection is not observable without SDK — branch outcome equivalent under mutation
+        if (_isNoopSpan(span))
+            return _withSyntheticIds(() => _spanHandler(fn, span));
+        return _spanHandler(fn, span);
+    });
+}
+/**
+ * Method/function decorator that wraps the target in withTrace().
+ * Span name defaults to the decorated method name.
+ *
+ * Usage (requires experimentalDecorators: true):
+ *   class Foo {
+ *     @trace('my.operation')
+ *     doWork() { ... }
+ *   }
+ */
+// Stryker disable BlockStatement: outer and inner decorator fns returning undefined leave descriptors unchanged — equivalent
+export function traceDecorator(name) {
+    return function (_target, propertyKey, descriptor) {
+        // Stryker enable BlockStatement
+        // Stryker disable next-line LogicalOperator: span name not observable with no-op tracer
+        const spanName = name ?? String(propertyKey);
+        const original = descriptor.value;
+        descriptor.value = function (...args) {
+            return withTrace(spanName, () => original.apply(this, args));
+        };
+        return descriptor;
+    };
+}

package/package.json

@@ -0,0 +1,139 @@
+{
+  "name": "@provide-io/telemetry",
+  "version": "0.2.2",
+  "description": "Structured logging, OTEL traces/metrics for TypeScript frontends — parity with provide.telemetry Python package",
+  "license": "Apache-2.0",
+  "author": "provide.io llc",
+  "homepage": "https://github.com/provide-io/provide-telemetry#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/provide-io/provide-telemetry.git",
+    "directory": "typescript"
+  },
+  "keywords": [
+    "telemetry",
+    "observability",
+    "opentelemetry",
+    "otel",
+    "tracing",
+    "metrics",
+    "logging",
+    "structlog",
+    "pino",
+    "w3c-traceparent"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./otel": {
+      "types": "./dist/otel.d.ts",
+      "browser": "./dist/otel-noop.js",
+      "default": "./dist/otel.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json",
+    "lint": "eslint src tests --max-warnings=0",
+    "lint:fix": "eslint src tests --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:mutation": "stryker run",
+    "test:memory": "npx tsx scripts/memory-audit.ts",
+    "perf": "tsx scripts/perf-smoke.ts",
+    "stress": "tsx scripts/stress-logging.ts && tsx scripts/stress-backpressure.ts && tsx scripts/stress-metrics.ts",
+    "bundle-size": "tsx scripts/bundle-size.ts",
+    "prepublishOnly": "npm run build && npm run test:coverage"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "pino": "^10.3.1"
+  },
+  "peerDependencies": {
+    "@opentelemetry/exporter-logs-otlp-http": "^0.214.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.214.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.214.0",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-logs": "^0.214.0",
+    "@opentelemetry/sdk-metrics": "^2.6.1",
+    "@opentelemetry/sdk-trace-base": "^2.6.1",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/exporter-logs-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-metrics-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/resources": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-logs": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-metrics": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    },
+    "react": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@opentelemetry/context-async-hooks": "^2.6.1",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.214.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.214.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.214.0",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-metrics": "^2.6.1",
+    "@opentelemetry/sdk-trace-base": "^2.6.1",
+    "@stryker-mutator/core": "^9.6.0",
+    "@stryker-mutator/vitest-runner": "^9.6.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.0.0",
+    "@types/node": "^25.5.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.3.7",
+    "@vitest/coverage-v8": "^4.1.2",
+    "eslint": "^10.1.0",
+    "eslint-config-prettier": "^10.0.0",
+    "fast-check": "^4.6.0",
+    "globals": "^17.4.0",
+    "happy-dom": "^20.8.8",
+    "prettier": "^3.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.3.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.57.2",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2"
+  }
+}

package/src/backpressure.ts

@@ -0,0 +1,68 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Bounded queue controls for telemetry signal paths.
+ * Mirrors Python provide.telemetry.backpressure.
+ */
+
+export interface QueuePolicy {
+  maxLogs: number;
+  maxTraces: number;
+  maxMetrics: number;
+}
+
+export interface QueueTicket {
+  signal: 'logs' | 'traces' | 'metrics';
+  token: number;
+}
+
+const DEFAULT_POLICY: QueuePolicy = { maxLogs: 0, maxTraces: 0, maxMetrics: 0 };
+
+let _policy: QueuePolicy = { ...DEFAULT_POLICY };
+let _tokenCounter = 1;
+const _acquired: Map<string, Set<number>> = new Map([
+  ['logs', new Set()],
+  ['traces', new Set()],
+  ['metrics', new Set()],
+]);
+
+export function setQueuePolicy(policy: Partial<QueuePolicy>): void {
+  _policy = { ..._policy, ...policy };
+}
+
+export function getQueuePolicy(): QueuePolicy {
+  return { ..._policy };
+}
+
+function _maxFor(signal: QueueTicket['signal']): number {
+  if (signal === 'logs') return _policy.maxLogs;
+  if (signal === 'traces') return _policy.maxTraces;
+  return _policy.maxMetrics;
+}
+
+export function tryAcquire(signal: QueueTicket['signal']): QueueTicket | null {
+  const max = _maxFor(signal);
+  if (max <= 0) return { signal, token: 0 };
+  const set = _acquired.get(signal);
+  // Stryker disable next-line ConditionalExpression: defensive guard — _acquired is initialized with all three signal keys, so get() never returns undefined
+  /* v8 ignore next */
+  if (!set) return null;
+  if (set.size >= max) return null;
+  const token = _tokenCounter++;
+  set.add(token);
+  return { signal, token };
+}
+
+export function release(ticket: QueueTicket): void {
+  // Stryker disable next-line ConditionalExpression: token=0 is the unlimited-queue sentinel; delete(0) from set is always a no-op
+  if (ticket.token === 0) return;
+  // Stryker disable next-line OptionalChaining: signal is always a key in _acquired (initialized in the Map constructor)
+  _acquired.get(ticket.signal)?.delete(ticket.token);
+}
+
+export function _resetBackpressureForTests(): void {
+  _policy = { ...DEFAULT_POLICY };
+  _tokenCounter = 1;
+  for (const set of _acquired.values()) set.clear();
+}