@quicore/tracelet-otel 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Carnival Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# @quicore/tracelet-otel 0.5.0
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional OpenTelemetry adapter: native spans, W3C propagation, bounded metrics and runtime cache export. Core and runtime remain dependency-free. The application supplies a tracer and optional meter; the adapter never registers global providers/context managers, starts samplers/exporters, installs signal handlers, or flushes/shuts down providers.
+
+## Installation and compatibility
+
+```sh
+npm install @quicore/tracelet-otel @opentelemetry/api@1.9.0
+```
+
+Requires API peer `@opentelemetry/api@1.9.0`; depends on `@quicore/tracelet@0.5.0` (internal bridge coupling) and `@opentelemetry/core@2.12.0` (W3C propagator). SDKs, exporters, context managers and the runtime sampler are application dependencies. The pinned test/example SDK is 2.12.0. API 1.10 and SDK 3 are **not** supported by this release's dependency contract.
+
+Engine range: Node ^18.19.0 or >=20.6.0. Windows tests passed on 18.20.8, 20.20.0, 22.22.0 and 24.13.0. Compatibility tests do not endorse EOL runtimes; Linux and other dependency combinations remain unverified. CJS and ESM named imports work. The npm package contains precompiled JavaScript; no build step is needed.
+
+## Basic use
+
+For this runnable local example, install the application's SDK dependencies:
+
+```sh
+npm install @opentelemetry/sdk-trace@2.12.0 @opentelemetry/sdk-metrics@2.12.0
+```
+
+The console exporter below is for local inspection. Configure your application's
+exporter, resources, sampling and bounded batch processing before deployment.
+
+```js
+import { createTraceletAdapter } from '@quicore/tracelet-otel';
+import { TracerProvider, SimpleSpanProcessor, ConsoleSpanExporter } from '@opentelemetry/sdk-trace';
+import { MeterProvider } from '@opentelemetry/sdk-metrics';
+
+const tracerProvider = new TracerProvider({
+  spanProcessors: [new SimpleSpanProcessor({ exporter: new ConsoleSpanExporter() })],
+});
+const meterProvider = new MeterProvider(); // Add a reader/exporter for metric delivery.
+const adapter = createTraceletAdapter({
+  tracer: tracerProvider.getTracer('my-service.tracelet', '0.5.0'),
+  meter: meterProvider.getMeter('my-service.tracelet', '0.5.0'),
+  operationNames: ['syncOrders'],
+  resourceTypes: ['system'],
+  businessMetrics: [{ name: 'orders', type: 'upDownCounter' }],
+  tagKeys: ['region'],
+});
+
+const work = adapter.create({ operationName: 'syncOrders' });
+try {
+  work.start().tag('region', 'west');
+  // Replace these example observations with measured application values.
+  work.recordIO({ status: 200, durationMs: 12, bytesIn: 120 });
+  work.increment('orders', 1).complete();
+  console.log(adapter.otelContext(work));
+} catch (error) {
+  work.fail(error);
+  throw error;
+} finally {
+  // In a service, do this once at shutdown after draining all work.
+  adapter.dispose();
+  await Promise.all([tracerProvider.shutdown(), meterProvider.shutdown()]);
+}
+```
+
+CommonJS: `const { createTraceletAdapter } = require('@quicore/tracelet-otel')`.
+To export runtime data, install `@quicore/tracelet-runtime` and pass an application-started
+sampler as `runtimeSampler`; the application also owns its shutdown.
+
+`withContext` requires an application-installed OTel context manager (for Node, AsyncLocalStorageContextManager). Without it the API's no-op manager cannot propagate active context through async work. Explicit parents and `createChildSpan()` do not need a global manager.
+
+## API
+
+| API | Behavior |
+| --- | --- |
+| `create(coreOptions, spanOptions?)` | Returns a normal Tracelet; no late attach to existing contexts |
+| `fromHeaders(headers, coreOptions, spanOptions?)` | Explicit W3C extraction; plain objects or native Headers |
+| `inject(tracelet, carrier?, {legacy?: boolean})` | Mutates/returns carrier; clears old W3C fields first; optional legacy trace/span IDs only |
+| `otelContext(tracelet)` | Detached native traceId/spanId/traceFlags; null for no-op provider, start failure or capacity shedding |
+| `withContext(tracelet, callback, ...args)` | Uses app context manager; returns callback value/promise and restores prior context |
+| `toDiagnostics()` | Detached fixed counters plus activeSpans and disposed |
+| `dispose()` | Idempotent; removes observable callbacks, ends active SDK spans as abandoned, rejects future creates/children |
+
+`spanOptions`: explicit `parentContext` wins, otherwise `useActiveContext: true` requests the active context; default is a root. `kind` is a native SpanKind, default INTERNAL. `fromHeaders` uses an explicit parent or extracted remote parent, otherwise root; `trustRemoteParent: false` discards remote ancestry. Inbound extraction has no implicit active-context fallback.
+
+| Factory option | Default / limits |
+| --- | --- |
+| tracer / meter | Required tracer / optional meter; injected app-owned objects |
+| operationNames / resourceTypes | Empty static registries, max 100 each; unmatched metric values become __other__ |
+| businessMetrics | Up to 100 unique {name, type, unit?}; type counter, upDownCounter, or gauge |
+| tagKeys | Empty allowlist, max 32 |
+| includeIdentity | false; true includes tenant/integration as trace attributes only |
+| sanitizeError | Optional synchronous function returning approved name/message/stack strings; no exception text/type/stack by default |
+| maxActiveSpans | 10000; configurable 1..100000 |
+| maxDimensionSets | 1000 per synchronous instrument; configurable 1..10000 |
+| runtimeSampler | Optional schema-1 sampler; requires meter; never started/stopped by adapter |
+
+Registration names match `[a-zA-Z][a-zA-Z0-9_.-]{0,127}` and must be unique/static. Register once at startup. Use one adapter per instrumentation scope/service lifetime: recreating adapters resets adapter budgets without clearing SDK aggregation, defeating a lifetime cardinality bound.
+
+## Lifecycle, identity and ownership
+
+Native spans start at construction, including PENDING time. Start adds an event; complete/fail/skip end once. Fail marks ERROR without a message; complete/skip retain UNSET. Failed I/O does not automatically fail the execution. End timestamps use the core epoch anchor plus monotonic elapsed time.
+
+Existing UUID/custom IDs and snapshot schema 3 remain unchanged. Legacy IDs become trace correlation attributes, never fabricated native IDs or metric dimensions. The SDK owns native identity/sampling. Children inherit native ancestry, can outlive parents, and can be created after parent completion. Parenting into an existing HTTP server span creates an INTERNAL business child by default.
+
+Per-context state is weakly keyed. Completed contexts retain native SpanContext for late children/correlation, not SDK Span objects or ancestor context trees. The bounded active-span registry drops excess native spans while retaining core behavior/metrics. Shed contexts have no native propagation context; a later child can become a new root if capacity returns. Unfinished spans occupy capacity until terminal/disposal; there is no automatic timeout policy.
+
+Disposal ends active SDK spans as abandoned without changing core lifecycle or fabricating terminal execution metrics. Existing contexts continue locally with telemetry disabled. Callback failures are diagnosed and contained. Disposal does not flush or guarantee delivery; exporter queues, retries, transport and shutdown order belong to the app/Collector.
+
+## Propagation and data policy
+
+W3C syntax validation uses OTel's propagator. Invalid/duplicate/ambiguous traceparent becomes a root and increments invalidParents. Valid tracestate survives. Baggage is never imported or injected; unrelated fields already in an outgoing carrier are untouched.
+
+Legacy-only incoming correlation starts a native root. Ambiguous custom headers still throw. Incoming tenant/integration headers are ignored: provide authenticated identity in coreOptions. Optional legacy dual-write sends correlation IDs only, unlike core's existing toTraceHeaders(), which can include identity.
+
+Tags export only allowlisted scalars or homogeneous scalar arrays (max 32); strings are capped at 1024 characters. Nested objects are omitted. Registered per-context gauges become span attributes, not global gauges. Exception fields need an explicit sanitizer, with 1024 characters per field. Async sanitizers are unsupported/diagnosed; native promise rejections are consumed. No raw errors are logged on failure.
+
+Operation names, resourceType and legacy IDs still reach trace attributes and may themselves contain sensitive values. Use static operation names and opaque identifiers. This is not automatic PHI/secret redaction or identity verification. SDK attribute limits may drop additional attributes.
+
+## Metrics
+
+Names are Tracelet-owned, not a claim of full semantic-convention compliance. Configure service/instance identity on application SDK resources. No tenant, integration, trace/span ID, URL or error text dimensions are used.
+
+| Instrument | Type / unit | Meaning |
+| --- | --- | --- |
+| tracelet.executions | Counter / {execution} | Accepted terminal transitions; operation, resource, outcome |
+| tracelet.execution.duration | Histogram / s | Construction-to-terminal time, same dimensions |
+| tracelet.io.attempts | Counter / {attempt} | Accepted attempts; operation, resource, success, coarse 1xx..5xx/other status |
+| tracelet.io.duration | Histogram / s | Valid individual durations, including zero |
+| tracelet.io.bytes.in / .out | Counter / By | Known byte observations |
+| tracelet.io.measurement.unavailable | Counter / {measurement} | Missing/invalid by field/reason plus I/O dimensions |
+| tracelet.business.NAME | Counter or UpDownCounter / configured unit | Registered deltas; Counter drops negative deltas, UpDownCounter preserves them |
+| tracelet.adapter.events | ObservableCounter / {event} | Fixed diagnostic reason counters |
+
+Unknown business names/types are diagnosed and omitted. Gauge registrations affect traces only; application-wide business gauges should use the application's meter directly. Snapshot reads/resetIO never replay/reset exported counters. Metrics are independent of trace sampling. Histograms receive individual observations, never local percentiles. Configure bucket boundaries and SDK cardinality limits in app-owned views/readers.
+
+Each synchronous instrument independently caps dimension sets and drops excess new sets. A bounded lifetime sum guard drops values that would make an instrument/dimension aggregate nonfinite; this is conservative for delta readers. It does not provide arbitrary precision or prevent downstream overflow when SDK views merge dimensions or services aggregate. SDKs may apply additional limits.
+
+### Runtime
+
+Cache export includes CPU user/system cumulative seconds, core-equivalent CPU utilization, RSS, uptime, isolate heap/external/array-buffer bytes, event-loop utilization and mean/max/p50/p95/p99 delay **gauges** in seconds. CPU time is an ObservableCounter; other measurements are gauges. Delay sample count and sampler interval are also gauges. Workers omit process metrics; isolate series include tracelet.thread.id. Array-buffer bytes are included in external memory; do not sum them.
+
+| Runtime instrument | Unit / dimensions |
+| --- | --- |
+| tracelet.process.cpu.time | s; cpu.mode=user/system |
+| tracelet.process.cpu.utilization | 1; core-equivalents, can exceed 1 |
+| tracelet.process.memory.rss | By |
+| tracelet.process.uptime | s |
+| tracelet.node.heap.used / .total | By; thread |
+| tracelet.node.memory.external / .array_buffers | By; thread |
+| tracelet.node.event_loop.utilization | 1; thread |
+| tracelet.node.event_loop.delay | s; thread, statistic=mean/max/p50/p95/p99 |
+| tracelet.node.event_loop.delay.samples | {sample}; thread, interval count (not cumulative) |
+| tracelet.runtime.sample.interval | s; thread |
+| tracelet.runtime.sample.age | s; thread |
+| tracelet.runtime.sample.valid | 1; no dimensions |
+| tracelet.runtime.sample.errors | {error}; thread, fixed reason |
+
+`tracelet.runtime.sample.age` reports seconds since last successful sample. `tracelet.runtime.sample.valid` is 1 only when running, status ok, and cache age <= three configured intervals; otherwise 0. `tracelet.runtime.sample.errors` is an ObservableCounter by fixed reason. Initial deltas and invalid groups are not observed. Multiple readers never collect/reset the sampler.
+
+**SDK history caveat:** the tested cumulative SDK retains prior values even when later callbacks omit them or are removed. Use sample.valid=1 and freshness when interpreting runtime data; omission does not guarantee remote series disappearance. After disposal even validity can remain in SDK history. Shut down/export app-owned providers deliberately; disposal is not remote series deletion. Partial samples conservatively mark the whole sample invalid.
+
+## Deployment limitations
+
+Package installation is separate from production-readiness validation. Collector/OTLP transport, host metrics, Linux, sustained retention/outage tests, SDK 3 migration and LogicMonitor ingestion remain separate work.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/index.js

@@ -0,0 +1,303 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createTraceletAdapter = createTraceletAdapter;
+var _api = require("@opentelemetry/api");
+var _core = require("@opentelemetry/core");
+var _tracelet = require("@quicore/tracelet");
+var _observe = require("@quicore/tracelet/internal/observe");
+var _metrics = require("./metrics.js");
+var _runtime = require("./runtime.js");
+var _nodeUtil = require("node:util");
+const timestamp = ms => [Math.floor(ms / 1000), Math.round(ms % 1000 * 1e6)];
+const DIAGNOSTICS = ['sdkErrors', 'spanLimitDrops', 'dimensionDrops', 'numericOverflowDrops', 'unregisteredMetrics', 'negativeCounterDrops', 'metricTypeDrops', 'invalidParents', 'runtimeErrors', 'sanitizerErrors'];
+const getter = {
+  keys: carrier => Object.keys(carrier),
+  get: (carrier, key) => carrier[key]
+};
+const setter = {
+  set: (carrier, key, value) => {
+    if (typeof carrier.set === 'function') carrier.set(key, value);else carrier[key] = value;
+  }
+};
+function carrierHeaders(headers) {
+  const result = Object.create(null);
+  const entries = typeof headers?.entries === 'function' ? headers.entries() : Object.entries(headers ?? {});
+  for (const [key, value] of entries) {
+    const k = key.toLowerCase();
+    if (k !== 'traceparent' && k !== 'tracestate') continue;
+    // Reject ambiguous parents before delegating syntax validation to W3C.
+    if (Object.hasOwn(result, k)) result[k] = '';else result[k] = Array.isArray(value) ? value.length === 1 ? value[0] : '' : value;
+    if (typeof result[k] !== 'string' || result[k].length > 512) result[k] = '';
+  }
+  return result;
+}
+function attribute(value) {
+  if (typeof value === 'string') return value.slice(0, 1024);
+  if (typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value)) return value;
+  if (Array.isArray(value) && value.length <= 32 && value.every(v => typeof v === typeof value[0] && ['string', 'boolean', 'number'].includes(typeof v) && (typeof v !== 'number' || Number.isFinite(v)))) return value.map(v => typeof v === 'string' ? v.slice(0, 1024) : v);
+  return undefined;
+}
+
+/** Explicit adapter: never registers globals, starts timers or owns providers. */
+function createTraceletAdapter(options = {}) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('options must be an object');
+  const {
+    tracer,
+    meter,
+    runtimeSampler,
+    sanitizeError
+  } = options;
+  if (!tracer || typeof tracer.startSpan !== 'function') throw new TypeError('An application-owned tracer is required');
+  if (sanitizeError !== undefined && typeof sanitizeError !== 'function') throw new TypeError('sanitizeError must be a synchronous function');
+  if (options.includeIdentity !== undefined && typeof options.includeIdentity !== 'boolean') throw new TypeError('includeIdentity must be boolean');
+  const tags = (0, _metrics.names)(options.tagKeys ?? [], 'tagKeys', 32);
+  const maxActive = options.maxActiveSpans ?? 10000;
+  if (!Number.isInteger(maxActive) || maxActive < 1 || maxActive > 100000) throw new TypeError('maxActiveSpans must be 1..100000');
+  const diagnostics = Object.fromEntries(DIAGNOSTICS.map(key => [key, 0]));
+  const diagnostic = key => {
+    diagnostics[key] = Math.min(Number.MAX_SAFE_INTEGER, diagnostics[key] + 1);
+  };
+  const metrics = (0, _metrics.createMetrics)(meter, options, diagnostic);
+  const states = new WeakMap();
+  const active = new Set();
+  const propagator = new _core.W3CTraceContextPropagator();
+  let disposed = false;
+  const detachRuntime = (0, _runtime.attachRuntime)(meter, runtimeSampler, diagnostic);
+  let diagnosticInstrument;
+  const diagnosticCallback = result => {
+    try {
+      for (const reason of DIAGNOSTICS) result.observe(diagnostics[reason], {
+        'tracelet.reason': reason
+      });
+    } catch {
+      diagnostic('sdkErrors');
+    }
+  };
+  try {
+    diagnosticInstrument = meter?.createObservableCounter('tracelet.adapter.events', {
+      unit: '{event}'
+    });
+    diagnosticInstrument?.addCallback(diagnosticCallback);
+  } catch (error) {
+    detachRuntime();
+    throw error;
+  }
+  const nativeContext = state => state.sc ? _api.trace.setSpanContext(_api.ROOT_CONTEXT, state.sc) : _api.ROOT_CONTEXT;
+  const lookup = value => {
+    const state = states.get((0, _observe.observationHandlerFor)(value));
+    if (!state) throw new TypeError('Context does not belong to this adapter');
+    return state;
+  };
+  function finish(state, endTime) {
+    const span = state.span;
+    state.span = null;
+    active.delete(state);
+    if (span) {
+      try {
+        span.end(endTime);
+      } catch {
+        diagnostic('sdkErrors');
+      }
+    }
+  }
+  function observe(state, event) {
+    if (disposed) return;
+    const terminal = event.type === 'lifecycle' && event.isFinal;
+    const time = timestamp(event.timing.startTimeEpochMs + event.timing.elapsedMs);
+    if (event.type === 'create') {
+      try {
+        if (active.size >= maxActive) {
+          diagnostic('spanLimitDrops');
+          return;
+        }
+        const id = event.identity;
+        const attrs = {
+          'tracelet.trace_id': id.traceId,
+          'tracelet.span_id': id.spanId,
+          'tracelet.resource_type': id.resourceType
+        };
+        if (id.parentSpanId) attrs['tracelet.parent_span_id'] = id.parentSpanId;
+        if (options.includeIdentity) {
+          if (id.tenantId) attrs['tracelet.tenant_id'] = id.tenantId;
+          if (id.integrationId) attrs['tracelet.integration_id'] = id.integrationId;
+        }
+        state.span = tracer.startSpan(id.operationName, {
+          kind: state.kind,
+          startTime: timestamp(event.timing.startTimeEpochMs),
+          attributes: attrs
+        }, state.parent);
+        if (disposed) {
+          finish(state, time);
+          return;
+        }
+        active.add(state);
+        const sc = state.span.spanContext();
+        state.sc = (0, _api.isSpanContextValid)(sc) ? Object.freeze({
+          ...sc,
+          isRemote: false
+        }) : null;
+      } catch {
+        diagnostic('sdkErrors');
+        finish(state, time);
+      } finally {
+        state.parent = null;
+      }
+      return;
+    }
+    // Metrics are independent of sampling and SDK span failures.
+    try {
+      metrics.observe(event, nativeContext(state), state.span);
+    } catch {
+      diagnostic('sdkErrors');
+    }
+    try {
+      const span = state.span;
+      if (!span) return;
+      if (event.type === 'tag' && tags.has(event.key)) {
+        const value = attribute(event.value);
+        if (value !== undefined) span.setAttribute(`tracelet.tag.${event.key}`, value);
+      } else if (event.type === 'lifecycle') {
+        if (terminal) {
+          span.setAttribute('tracelet.outcome', event.state.toLowerCase());
+          if (event.state === 'FAILED') {
+            span.setStatus({
+              code: _api.SpanStatusCode.ERROR
+            });
+            if (sanitizeError) {
+              try {
+                const safe = sanitizeError(event.error);
+                // Only explicit, bounded exception fields are accepted.
+                if (safe && typeof safe.then === 'function') {
+                  if (_nodeUtil.types.isPromise(safe)) Promise.prototype.then.call(safe, undefined, () => {});
+                  diagnostic('sanitizerErrors');
+                } else if (safe && typeof safe === 'object') {
+                  const exception = {};
+                  for (const key of ['name', 'message', 'stack']) if (typeof safe[key] === 'string') exception[key] = safe[key].slice(0, 1024);
+                  if (Object.keys(exception).length) span.recordException(exception, time);
+                }
+              } catch {
+                diagnostic('sanitizerErrors');
+              }
+            }
+          }
+        } else span.addEvent('tracelet.running', {}, time);
+      }
+    } catch {
+      diagnostic('sdkErrors');
+    } finally {
+      if (terminal) finish(state, time);
+    }
+  }
+  function create(traceletOptions, spanOptions = {}) {
+    if (disposed) throw new Error('Adapter is disposed');
+    if (!spanOptions || typeof spanOptions !== 'object') throw new TypeError('spanOptions must be an object');
+    const kind = spanOptions.kind ?? _api.SpanKind.INTERNAL;
+    if (![0, 1, 2, 3, 4].includes(kind)) throw new TypeError('Invalid span kind');
+    let rootParent = spanOptions.parentContext ?? (spanOptions.useActiveContext ? _api.context.active() : _api.ROOT_CONTEXT);
+    if (!rootParent || typeof rootParent.getValue !== 'function') throw new TypeError('Invalid parentContext');
+    function factory(parentHandler) {
+      if (disposed) throw new Error('Adapter is disposed');
+      const state = {
+        span: null,
+        sc: null,
+        parent: parentHandler ? nativeContext(states.get(parentHandler)) : rootParent,
+        kind: parentHandler ? _api.SpanKind.INTERNAL : kind
+      };
+      const handler = event => {
+        observe(state, event);
+      };
+      states.set(handler, state);
+      return handler;
+    }
+    try {
+      return (0, _observe.createObservationTree)(traceletOptions, factory);
+    } finally {
+      rootParent = null;
+    } // Never retain an application's full context tree.
+  }
+  return Object.freeze({
+    create,
+    fromHeaders(headers, traceletOptions, spanOptions = {}) {
+      const legacy = _tracelet.Tracelet._normalizeHeaders(headers);
+      const carrier = carrierHeaders(headers);
+      let parent = _api.ROOT_CONTEXT;
+      if (spanOptions.trustRemoteParent !== false) {
+        parent = propagator.extract(_api.ROOT_CONTEXT, carrier, getter);
+        if (Object.hasOwn(carrier, 'traceparent') && !_api.trace.getSpanContext(parent)) diagnostic('invalidParents');
+      }
+      // Incoming tenant/integration values are not authenticated identity.
+      return create({
+        traceId: legacy['x-trace-id'] || undefined,
+        parentSpanId: legacy['x-span-id'] || null,
+        ...traceletOptions
+      }, {
+        ...spanOptions,
+        parentContext: spanOptions.parentContext ?? parent
+      });
+    },
+    inject(value, carrier = {}, {
+      legacy = false
+    } = {}) {
+      const state = lookup(value);
+      if (typeof carrier.delete === 'function' && typeof carrier.set === 'function') {
+        carrier.delete('traceparent');
+        carrier.delete('tracestate');
+      } else {
+        for (const key of Object.keys(carrier)) if (['traceparent', 'tracestate'].includes(key.toLowerCase())) delete carrier[key];
+      }
+      propagator.inject(nativeContext(state), carrier, setter);
+      if (legacy) {
+        // Opt-in legacy correlation only; identity must not cross trust boundaries implicitly.
+        setter.set(carrier, 'x-trace-id', value.traceId);
+        setter.set(carrier, 'x-span-id', value.spanId);
+      }
+      return carrier;
+    },
+    otelContext(value) {
+      const sc = lookup(value).sc;
+      return sc ? {
+        traceId: sc.traceId,
+        spanId: sc.spanId,
+        traceFlags: sc.traceFlags
+      } : null;
+    },
+    withContext(value, callback, ...args) {
+      const state = lookup(value);
+      const base = _api.trace.deleteSpan(_api.context.active());
+      const ctx = state.span ? _api.trace.setSpan(base, state.span) : state.sc ? _api.trace.setSpanContext(base, state.sc) : base;
+      return _api.context.with(ctx, callback, undefined, ...args);
+    },
+    toDiagnostics() {
+      return {
+        ...diagnostics,
+        activeSpans: active.size,
+        disposed
+      };
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      try {
+        detachRuntime();
+      } catch {
+        diagnostic('sdkErrors');
+      }
+      try {
+        diagnosticInstrument?.removeCallback(diagnosticCallback);
+      } catch {
+        diagnostic('sdkErrors');
+      }
+      for (const state of active) {
+        try {
+          state.span.setAttribute('tracelet.outcome', 'abandoned');
+        } catch {
+          diagnostic('sdkErrors');
+        }
+        finish(state); // SDK monotonic end time; no fabricated core terminal event.
+      }
+    }
+  });
+}

package/dist/metrics.js

@@ -0,0 +1,104 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createMetrics = createMetrics;
+exports.names = names;
+var _api = require("@opentelemetry/api");
+function names(values, label, limit = 100) {
+  if (!Array.isArray(values) || values.length > limit || values.some(v => typeof v !== 'string' || !/^[a-zA-Z][a-zA-Z0-9_.-]{0,127}$/.test(v)) || new Set(values).size !== values.length) {
+    throw new TypeError(`${label} must contain at most ${limit} unique static names`);
+  }
+  return new Set(values);
+}
+function createMetrics(meter, options, diagnostic) {
+  const operations = names(options.operationNames ?? [], 'operationNames');
+  const resources = names(options.resourceTypes ?? [], 'resourceTypes');
+  const definitions = options.businessMetrics ?? [];
+  if (!Array.isArray(definitions) || definitions.length > 100) throw new TypeError('businessMetrics must be an array of at most 100 registrations');
+  names(definitions.map(d => d?.name), 'business metric names');
+  for (const d of definitions) {
+    if (!['counter', 'upDownCounter', 'gauge'].includes(d.type) || d.unit !== undefined && (typeof d.unit !== 'string' || d.unit.length > 32)) throw new TypeError('Invalid business metric registration');
+  }
+  const max = options.maxDimensionSets ?? 1000;
+  if (!Number.isInteger(max) || max < 1 || max > 10000) throw new TypeError('maxDimensionSets must be 1..10000');
+  // Each synchronous instrument has an independent, lifetime-bounded label set.
+  // Overflow is dropped and counted, never silently merged with real labels.
+  function instrument(method, name, unit, recordMethod) {
+    const target = meter?.[method](name, {
+      unit
+    });
+    const seen = new Map();
+    return (value, attributes, ctx = _api.ROOT_CONTEXT) => {
+      if (!target) return;
+      const key = JSON.stringify(attributes);
+      if (!seen.has(key)) {
+        if (seen.size >= max) {
+          diagnostic('dimensionDrops');
+          return;
+        }
+        seen.set(key, 0);
+      }
+      const sum = seen.get(key) + value;
+      if (!Number.isFinite(sum)) {
+        diagnostic('numericOverflowDrops');
+        return;
+      }
+      seen.set(key, sum);
+      try {
+        target[recordMethod](value, attributes, ctx);
+      } catch {
+        diagnostic('sdkErrors');
+      }
+    };
+  }
+  const executions = instrument('createCounter', 'tracelet.executions', '{execution}', 'add');
+  const duration = instrument('createHistogram', 'tracelet.execution.duration', 's', 'record');
+  const attempts = instrument('createCounter', 'tracelet.io.attempts', '{attempt}', 'add');
+  const latency = instrument('createHistogram', 'tracelet.io.duration', 's', 'record');
+  const bytesIn = instrument('createCounter', 'tracelet.io.bytes.in', 'By', 'add');
+  const bytesOut = instrument('createCounter', 'tracelet.io.bytes.out', 'By', 'add');
+  const unavailable = instrument('createCounter', 'tracelet.io.measurement.unavailable', '{measurement}', 'add');
+  const business = new Map(definitions.map(d => [d.name, {
+    type: d.type,
+    write: d.type === 'gauge' ? null : instrument(d.type === 'counter' ? 'createCounter' : 'createUpDownCounter', `tracelet.business.${d.name}`, d.unit ?? '1', 'add')
+  }]));
+  const attributes = e => ({
+    'tracelet.operation': operations.has(e.identity.operationName) ? e.identity.operationName : '__other__',
+    'tracelet.resource': resources.has(e.identity.resourceType) ? e.identity.resourceType : '__other__'
+  });
+  return {
+    observe(e, ctx, span) {
+      const attrs = attributes(e);
+      if (e.type === 'lifecycle' && e.isFinal) {
+        attrs['tracelet.outcome'] = e.state.toLowerCase();
+        executions(1, attrs, ctx);
+        duration(e.timing.elapsedMs / 1000, attrs, ctx);
+      } else if (e.type === 'io') {
+        attrs['tracelet.io.success'] = e.isSuccess;
+        attrs['tracelet.io.status_class'] = /^[1-5][0-9]{2}$/.test(String(e.status)) ? `${String(e.status)[0]}xx` : 'other';
+        attempts(1, attrs, ctx);
+        for (const [field, writer, scale] of [['durationMs', latency, 1000], ['bytesIn', bytesIn, 1], ['bytesOut', bytesOut, 1]]) {
+          const observation = e.measurements[field];
+          if (observation.validity === 'valid') writer(observation.value / scale, attrs, ctx);else unavailable(1, {
+            ...attrs,
+            'tracelet.measurement': field,
+            'tracelet.reason': observation.validity
+          }, ctx);
+        }
+      } else if (e.type === 'counter' || e.type === 'gauge') {
+        const registration = business.get(e.name);
+        if (!registration) {
+          diagnostic('unregisteredMetrics');
+          return;
+        }
+        if (e.type === 'gauge' && registration.type === 'gauge') {
+          span?.setAttribute(`tracelet.gauge.${e.name}`, e.value);
+        } else if (e.type === 'counter' && registration.type !== 'gauge') {
+          if (registration.type === 'counter' && e.delta < 0) diagnostic('negativeCounterDrops');else registration.write(e.delta, attrs, ctx);
+        } else diagnostic('metricTypeDrops');
+      }
+    }
+  };
+}

package/dist/runtime.js

@@ -0,0 +1,83 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.attachRuntime = attachRuntime;
+// No sampler ownership: readers only inspect the cache, never collect or reset.
+function attachRuntime(meter, sampler, diagnostic) {
+  if (!sampler) return () => {};
+  if (!meter || typeof sampler.toSnapshot !== 'function') throw new TypeError('runtimeSampler requires a meter and toSnapshot()');
+  const instruments = [];
+  const make = (name, unit, counter = false) => {
+    const result = meter[counter ? 'createObservableCounter' : 'createObservableGauge'](name, {
+      unit
+    });
+    instruments.push(result);
+    return result;
+  };
+  const cpu = make('tracelet.process.cpu.time', 's', true);
+  const utilization = make('tracelet.process.cpu.utilization', '1');
+  const rss = make('tracelet.process.memory.rss', 'By');
+  const uptime = make('tracelet.process.uptime', 's');
+  const memory = Object.fromEntries(['heapUsedBytes', 'heapTotalBytes', 'externalBytes', 'arrayBuffersBytes'].map((key, i) => [key, make(['tracelet.node.heap.used', 'tracelet.node.heap.total', 'tracelet.node.memory.external', 'tracelet.node.memory.array_buffers'][i], 'By')]));
+  const elu = make('tracelet.node.event_loop.utilization', '1');
+  const delay = make('tracelet.node.event_loop.delay', 's');
+  const count = make('tracelet.node.event_loop.delay.samples', '{sample}');
+  const interval = make('tracelet.runtime.sample.interval', 's');
+  const age = make('tracelet.runtime.sample.age', 's');
+  const valid = make('tracelet.runtime.sample.valid', '1');
+  const errors = make('tracelet.runtime.sample.errors', '{error}', true);
+  const reasons = ['clock', 'cpu', 'memory', 'uptime', 'eventLoopUtilization', 'eventLoopDelay', 'monitor', 'timer'];
+  const callback = result => {
+    let scope = {};
+    try {
+      const s = sampler.toSnapshot();
+      if (s.schemaVersion !== 1) throw new Error('Unsupported runtime schema');
+      // Stopped/stale caches must not look like fresh process measurements.
+      scope = {
+        'tracelet.thread.id': s.scope.threadId
+      };
+      const observe = (instrument, value, attrs = scope) => {
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0) result.observe(instrument, value, attrs);
+      };
+      observe(age, s.lastSuccessfulSampleAgeSeconds);
+      const fresh = s.running && s.sampleAgeSeconds !== null && s.sampleAgeSeconds <= s.config.intervalMs / 1000 * 3;
+      observe(valid, fresh && s.status === 'ok' ? 1 : 0, {});
+      for (const reason of reasons) observe(errors, s.diagnostics.errors[reason], {
+        ...scope,
+        'tracelet.reason': reason
+      });
+      if (!fresh) return;
+      observe(interval, s.intervalSeconds);
+      if (s.scope.processMetricsEnabled && s.process) {
+        const processScope = {}; // Process resource identity belongs to the SDK resource.
+        observe(cpu, s.process.cpu?.userSeconds, {
+          'cpu.mode': 'user'
+        });
+        observe(cpu, s.process.cpu?.systemSeconds, {
+          'cpu.mode': 'system'
+        });
+        observe(utilization, s.process.cpu?.utilization, processScope);
+        observe(rss, s.process.rssBytes, processScope);
+        observe(uptime, s.process.uptimeSeconds, processScope);
+      }
+      for (const [key, instrument] of Object.entries(memory)) observe(instrument, s.node.memory?.[key]);
+      observe(elu, s.node.eventLoop?.utilization);
+      observe(count, s.node.eventLoop?.delay?.sampleCount);
+      for (const statistic of ['mean', 'max', 'p50', 'p95', 'p99']) observe(delay, s.node.eventLoop?.delay?.[`${statistic}Seconds`], {
+        ...scope,
+        'tracelet.statistic': statistic
+      });
+    } catch {
+      diagnostic('runtimeErrors');
+      try {
+        result.observe(valid, 0, {});
+      } catch {
+        diagnostic('sdkErrors');
+      }
+    }
+  };
+  meter.addBatchObservableCallback(callback, instruments);
+  return () => meter.removeBatchObservableCallback(callback, instruments);
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@quicore/tracelet-otel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "description": "Explicit Tracelet adapter for application-owned OpenTelemetry providers",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^18.19.0 || >=20.6.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": ">=1.9.0 <1.10.0"
+  },
+  "dependencies": {
+    "@quicore/tracelet": "0.5.0",
+    "@opentelemetry/core": "2.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "tracelet",
+    "opentelemetry",
+    "tracing",
+    "metrics",
+    "w3c"
+  ]
+}