@foam-ai/node-cliengo 0.1.0-alpha.1 → 0.1.0-alpha.10

package/dist/node-cliengo/src/logs/pino-destination.js

@@ -22,17 +22,22 @@
  *     60→FATAL. Unknown numeric levels default to INFO.
  *   - Pino uses `msg` for the message field (not `message` like Winston). We
  *     check both for compatibility with custom Pino configs.
- *   - Internal Pino fields (pid, hostname, time) are excluded from attributes
- *     to avoid noise. All other fields are forwarded.
+ *   - Trace context (traceId, spanId, traceparent) is read from the parsed
+ *     JSON line, NOT from getTraceContext(). The pino mixin injects these at
+ *     log-write time (when NR's transaction is still active). The stream write
+ *     happens asynchronously — by then NR's transaction has ended, so calling
+ *     getTraceContext() here would return empty strings.
+ *   - Internal Pino fields (pid, hostname, time) and trace fields (traceId,
+ *     spanId, traceparent) are excluded from forwarded attributes.
  *   - Callback always called — never blocks the Pino stream pipeline.
  *   - Buffer chunks: converted to string before parsing (handles both Buffer
  *     and string inputs from Node streams).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createPinoDestination = createPinoDestination;
+const api_1 = require("@opentelemetry/api");
 const api_logs_1 = require("@opentelemetry/api-logs");
 const node_stream_1 = require("node:stream");
-const trace_bridge_1 = require("../trace-bridge");
 const PINO_LEVEL_MAP = {
     10: api_logs_1.SeverityNumber.TRACE,
     20: api_logs_1.SeverityNumber.DEBUG,
@@ -66,16 +71,23 @@ function createPinoDestination(loggerProvider, serviceName) {
                 const msg = parsed.msg ?? parsed.message ?? '';
                 const severity = PINO_LEVEL_MAP[level] ?? api_logs_1.SeverityNumber.INFO;
                 const severityText = PINO_LEVEL_TEXT[level] ?? 'INFO';
-                const ctx = (0, trace_bridge_1.getTraceContext)();
+                // Read trace context from the parsed JSON line — the pino mixin already
+                // injected traceId/spanId/traceparent at log-write time (when the NR
+                // transaction was still active). Calling getTraceContext() here would be
+                // too late — the stream write happens asynchronously after NR's
+                // transaction has ended.
+                const traceId = parsed.traceId ?? '';
+                const spanId = parsed.spanId ?? '';
                 const attributes = {};
-                if (ctx.traceId) {
-                    attributes['trace.id'] = ctx.traceId;
+                if (traceId) {
+                    attributes['trace.id'] = traceId;
                 }
-                if (ctx.spanId) {
-                    attributes['span.id'] = ctx.spanId;
+                if (spanId) {
+                    attributes['span.id'] = spanId;
                 }
+                const SKIP_KEYS = new Set(['level', 'msg', 'message', 'time', 'pid', 'hostname', 'traceId', 'spanId', 'traceparent']);
                 for (const [key, val] of Object.entries(parsed)) {
-                    if (key !== 'level' && key !== 'msg' && key !== 'message' && key !== 'time' && key !== 'pid' && key !== 'hostname') {
+                    if (!SKIP_KEYS.has(key)) {
                         try {
                             attributes[key] = typeof val === 'string' ? val : JSON.stringify(val);
                         }
@@ -84,11 +96,24 @@ function createPinoDestination(loggerProvider, serviceName) {
                         }
                     }
                 }
+                // Build an OTel Context carrying the SpanContext so the SDK stamps the
+                // native traceId/spanId fields on the exported OTLP LogRecord. Without
+                // this, backends can't correlate logs to traces.
+                let logContext;
+                if (traceId && spanId) {
+                    logContext = api_1.trace.setSpanContext(api_1.ROOT_CONTEXT, {
+                        traceId,
+                        spanId,
+                        traceFlags: 1,
+                        isRemote: true,
+                    });
+                }
                 otelLogger.emit({
                     body: msg,
                     severityNumber: severity,
                     severityText,
                     attributes,
+                    ...(logContext && { context: logContext }),
                 });
             }
             catch {

package/dist/node-cliengo/src/logs/pino-mixin.d.ts

@@ -11,10 +11,11 @@
  * Used by kori (Fastify built-in Pino) and cb-proxy (Pino + pino-http).
  *
  * Edge cases covered:
- *   - NR not loaded or no active transaction: returns { traceId: '', spanId: '',
- *     traceparent: '' }. Consistent schema — log parsers always see the fields.
- *   - getTraceContext throws: catch returns the same empty-string object.
- *     Never crashes logging.
+ *   - NR not loaded or no active transaction: returns {} so it doesn't
+ *     overwrite valid trace context injected by pino-http's customProps
+ *     (Pino serializes mixin fields after customProps — duplicate keys
+ *     in JSON take the last value).
+ *   - getTraceContext throws: catch returns {}. Never crashes logging.
  *   - Lazy evaluation: the mixin is called at log-write time, not at Pino
  *     construction time, so trace context is always current.
  *   - Works with pino-pretty in development — fields appear in pretty output.

package/dist/node-cliengo/src/logs/pino-mixin.js

@@ -12,10 +12,11 @@
  * Used by kori (Fastify built-in Pino) and cb-proxy (Pino + pino-http).
  *
  * Edge cases covered:
- *   - NR not loaded or no active transaction: returns { traceId: '', spanId: '',
- *     traceparent: '' }. Consistent schema — log parsers always see the fields.
- *   - getTraceContext throws: catch returns the same empty-string object.
- *     Never crashes logging.
+ *   - NR not loaded or no active transaction: returns {} so it doesn't
+ *     overwrite valid trace context injected by pino-http's customProps
+ *     (Pino serializes mixin fields after customProps — duplicate keys
+ *     in JSON take the last value).
+ *   - getTraceContext throws: catch returns {}. Never crashes logging.
  *   - Lazy evaluation: the mixin is called at log-write time, not at Pino
  *     construction time, so trace context is always current.
  *   - Works with pino-pretty in development — fields appear in pretty output.
@@ -27,6 +28,9 @@ function createPinoMixin() {
     return () => {
         try {
             const ctx = (0, trace_bridge_1.getTraceContext)();
+            if (!ctx.traceId) {
+                return {};
+            }
             return {
                 traceId: ctx.traceId,
                 spanId: ctx.spanId,
@@ -34,7 +38,7 @@ function createPinoMixin() {
             };
         }
         catch {
-            return { traceId: '', spanId: '', traceparent: '' };
+            return {};
         }
     };
 }

package/dist/node-cliengo/src/metrics/instruments.d.ts

@@ -1,6 +1,5 @@
 /**
- * Pre-built OTel metric instruments for queue processing, plus factories
- * for service-specific custom metrics.
+ * Pre-built OTel metric instruments for queue processing.
  *
  * Why this file exists:
  *   Provides three auto-recorded instruments that wrapSqsConsumer and
@@ -9,15 +8,14 @@
  *   - messageProcessingErrors (counter): how many processing attempts fail
  *   - messagesProcessed (counter): total messages processed (success + error)
  *
- *   Also provides customHistogram/customCounter/customGauge factories for
- *   service-specific domain metrics (LLM duration in gpt-intentions, webhook
- *   processing time in cb-proxy, automation duration in kori).
+ *   These follow OTel semantic conventions for messaging. They are NOT
+ *   Cliengo-specific — any service with queue consumers gets them for free.
+ *
+ *   For service-specific domain metrics (LLM duration, webhook processing time,
+ *   automation duration), services use foam.meter directly:
+ *     const h = foam.meter.createHistogram('llm.duration', { unit: 'ms' });
  *
  * Edge cases covered:
- *   - Custom instrument idempotency: calling customHistogram('llm.duration', ...)
- *     twice returns the same Histogram instance (cached by name). OTel SDKs
- *     already handle duplicate instrument creation, but caching avoids the
- *     overhead of repeated createHistogram calls in hot paths.
  *   - MeterProvider is non-global — our metrics never conflict with NR's
  *     internal metrics or any other OTel MeterProvider in the process.
  *   - PeriodicExportingMetricReader (configured in init.ts) exports every 60s
@@ -25,5 +23,5 @@
  *     attached and no timer runs.
  */
 import type { MeterProvider } from '@opentelemetry/sdk-metrics';
-import type { BridgeMetrics } from '../types';
-export declare function createBridgeMetrics(meterProvider: MeterProvider, serviceName: string): BridgeMetrics;
+import type { FoamMetrics } from '../types';
+export declare function createFoamMetrics(meterProvider: MeterProvider, serviceName: string): FoamMetrics;

package/dist/node-cliengo/src/metrics/instruments.js

@@ -1,7 +1,6 @@
 "use strict";
 /**
- * Pre-built OTel metric instruments for queue processing, plus factories
- * for service-specific custom metrics.
+ * Pre-built OTel metric instruments for queue processing.
  *
  * Why this file exists:
  *   Provides three auto-recorded instruments that wrapSqsConsumer and
@@ -10,15 +9,14 @@
  *   - messageProcessingErrors (counter): how many processing attempts fail
  *   - messagesProcessed (counter): total messages processed (success + error)
  *
- *   Also provides customHistogram/customCounter/customGauge factories for
- *   service-specific domain metrics (LLM duration in gpt-intentions, webhook
- *   processing time in cb-proxy, automation duration in kori).
+ *   These follow OTel semantic conventions for messaging. They are NOT
+ *   Cliengo-specific — any service with queue consumers gets them for free.
+ *
+ *   For service-specific domain metrics (LLM duration, webhook processing time,
+ *   automation duration), services use foam.meter directly:
+ *     const h = foam.meter.createHistogram('llm.duration', { unit: 'ms' });
  *
  * Edge cases covered:
- *   - Custom instrument idempotency: calling customHistogram('llm.duration', ...)
- *     twice returns the same Histogram instance (cached by name). OTel SDKs
- *     already handle duplicate instrument creation, but caching avoids the
- *     overhead of repeated createHistogram calls in hot paths.
  *   - MeterProvider is non-global — our metrics never conflict with NR's
  *     internal metrics or any other OTel MeterProvider in the process.
  *   - PeriodicExportingMetricReader (configured in init.ts) exports every 60s
@@ -26,53 +24,19 @@
  *     attached and no timer runs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createBridgeMetrics = createBridgeMetrics;
-function createBridgeMetrics(meterProvider, serviceName) {
+exports.createFoamMetrics = createFoamMetrics;
+function createFoamMetrics(meterProvider, serviceName) {
     const meter = meterProvider.getMeter(serviceName);
-    const messageProcessingDuration = meter.createHistogram('messaging.process.duration', {
-        description: 'Time to process a queue message',
-        unit: 'ms',
-    });
-    const messageProcessingErrors = meter.createCounter('messaging.process.errors', {
-        description: 'Number of queue message processing errors',
-    });
-    const messagesProcessed = meter.createCounter('messaging.process.count', {
-        description: 'Number of queue messages processed',
-    });
-    const instrumentCache = new Map();
     return {
-        messageProcessingDuration,
-        messageProcessingErrors,
-        messagesProcessed,
-        customHistogram(name, description, unit) {
-            const key = `histogram:${name}`;
-            const existing = instrumentCache.get(key);
-            if (existing) {
-                return existing;
-            }
-            const h = meter.createHistogram(name, { description, unit });
-            instrumentCache.set(key, h);
-            return h;
-        },
-        customCounter(name, description, unit) {
-            const key = `counter:${name}`;
-            const existing = instrumentCache.get(key);
-            if (existing) {
-                return existing;
-            }
-            const c = meter.createCounter(name, { description, unit });
-            instrumentCache.set(key, c);
-            return c;
-        },
-        customGauge(name, description, unit) {
-            const key = `gauge:${name}`;
-            const existing = instrumentCache.get(key);
-            if (existing) {
-                return existing;
-            }
-            const g = meter.createObservableGauge(name, { description, unit });
-            instrumentCache.set(key, g);
-            return g;
-        },
+        messageProcessingDuration: meter.createHistogram('messaging.process.duration', {
+            description: 'Time to process a queue message',
+            unit: 'ms',
+        }),
+        messageProcessingErrors: meter.createCounter('messaging.process.errors', {
+            description: 'Number of queue message processing errors',
+        }),
+        messagesProcessed: meter.createCounter('messaging.process.count', {
+            description: 'Number of queue messages processed',
+        }),
     };
 }

package/dist/node-cliengo/src/nr.d.ts

@@ -14,7 +14,7 @@
  *      hsm-backend (conditional NR loading).
  *   2. Module cache: `require.cache[require.resolve('newrelic')]` — works for
  *      CJS services (combee, gpt-intentions, cb-proxy) where NR is loaded at
- *      the top of the entry file before the bridge initializes.
+ *      the top of the entry file before Foam initializes.
  *   3. Fallback: NOOP_NR stub that returns empty trace metadata and calls
  *      handler functions directly without creating background transactions.
  *

package/dist/node-cliengo/src/nr.js

@@ -15,7 +15,7 @@
  *      hsm-backend (conditional NR loading).
  *   2. Module cache: `require.cache[require.resolve('newrelic')]` — works for
  *      CJS services (combee, gpt-intentions, cb-proxy) where NR is loaded at
- *      the top of the entry file before the bridge initializes.
+ *      the top of the entry file before Foam initializes.
  *   3. Fallback: NOOP_NR stub that returns empty trace metadata and calls
  *      handler functions directly without creating background transactions.
  *

package/dist/node-cliengo/src/sns.d.ts

@@ -8,10 +8,7 @@
  *   alongside the existing ones. This function spread-merges it in.
  *
  * Edge cases covered:
- *   - No active NR transaction (buildTraceparent returns undefined): the
- *     original attributes are returned unchanged — no traceparent key added.
- *   - Empty attrs {}: returns just { traceparent: ... } if NR is active,
- *     or {} if not. Never crashes.
+ *   - Empty attrs {}: returns { traceparent: ... }. Never crashes.
  *   - Existing traceparent in attrs: overwritten with the current value
  *     (spread puts our key last).
  */

package/dist/node-cliengo/src/sns.js

@@ -9,10 +9,7 @@
  *   alongside the existing ones. This function spread-merges it in.
  *
  * Edge cases covered:
- *   - No active NR transaction (buildTraceparent returns undefined): the
- *     original attributes are returned unchanged — no traceparent key added.
- *   - Empty attrs {}: returns just { traceparent: ... } if NR is active,
- *     or {} if not. Never crashes.
+ *   - Empty attrs {}: returns { traceparent: ... }. Never crashes.
  *   - Existing traceparent in attrs: overwritten with the current value
  *     (spread puts our key last).
  */
@@ -20,12 +17,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.injectSnsAttributes = injectSnsAttributes;
 const trace_bridge_1 = require("./trace-bridge");
 function injectSnsAttributes(attrs) {
-    const tp = (0, trace_bridge_1.buildTraceparent)();
-    if (!tp) {
-        return attrs;
-    }
     return {
         ...attrs,
-        traceparent: { DataType: 'String', StringValue: tp },
+        traceparent: { DataType: 'String', StringValue: (0, trace_bridge_1.buildTraceparent)() },
     };
 }

package/dist/node-cliengo/src/sqs.d.ts

@@ -28,8 +28,8 @@
  *     service's own retry/DLQ logic is unaffected.
  *   - NR not loaded: execute() runs without startBackgroundTransaction — OTel
  *     span still created, metrics still recorded.
- *   - metrics is undefined (inert bridge): all metrics?.xxx calls are no-ops.
+ *   - metrics is undefined (inert foam instance): all metrics?.xxx calls are no-ops.
  */
 import { type Tracer } from '@opentelemetry/api';
-import type { BridgeMetrics, SqsMessage } from './types';
-export declare function wrapSqsConsumer(tracer: Tracer, spanName: string, msg: SqsMessage, fn: () => Promise<void>, metrics?: BridgeMetrics): Promise<void>;
+import type { FoamMetrics, SqsMessage } from './types';
+export declare function wrapSqsConsumer(tracer: Tracer, spanName: string, msg: SqsMessage, fn: () => Promise<void>, metrics?: FoamMetrics): Promise<void>;

package/dist/node-cliengo/src/sqs.js

@@ -29,7 +29,7 @@
  *     service's own retry/DLQ logic is unaffected.
  *   - NR not loaded: execute() runs without startBackgroundTransaction — OTel
  *     span still created, metrics still recorded.
- *   - metrics is undefined (inert bridge): all metrics?.xxx calls are no-ops.
+ *   - metrics is undefined (inert foam instance): all metrics?.xxx calls are no-ops.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.wrapSqsConsumer = wrapSqsConsumer;

package/dist/node-cliengo/src/trace-bridge.d.ts

@@ -1,39 +1,43 @@
 /**
- * W3C trace context bridge between New Relic and OpenTelemetry.
+ * W3C trace context utilities for New Relic and OpenTelemetry interop.
  *
  * Why this file exists:
- *   NR owns the active trace (it creates transactions via http monkey-patching),
- *   but our OTel spans need to share the same traceId so Foam and NR traces
- *   correlate. This module reads NR's trace metadata and converts it to/from
- *   W3C traceparent format (`00-{traceId}-{spanId}-{flags}`).
+ *   Reads trace context from two sources (NR first, then OTel's own active
+ *   span) and converts it to/from W3C traceparent format. This means trace
+ *   propagation works whether NR is installed, partially loaded, or completely
+ *   removed.
  *
- * Functions:
- *   - buildTraceparent(): reads NR's active traceId/spanId, returns a W3C
- *     traceparent string. Used by producers to inject into SNS attributes or
- *     BullMQ/Bull job data. Returns undefined when NR is not loaded or no
- *     active transaction exists.
- *   - extractParentContext(): parses a traceparent string into an OTel Context
- *     with a remote SpanContext. Used by consumers to link their OTel spans
- *     back to the producer's trace. Returns ROOT_CONTEXT on malformed input.
- *   - getTraceContext(): returns { traceId, spanId, traceparent } for log
- *     enrichment. Called lazily at log-write time (not at format creation time)
- *     so the trace context is always current.
+ * Two resolution modes:
+ *   resolveActiveTraceIds() — NR → OTel active span → empty strings.
+ *     Used by getTraceContext() (log enrichment) and createPinoMixin().
+ *     Never generates IDs — returns empty when no real source exists, so
+ *     it doesn't overwrite valid IDs injected by pino-http's customProps.
+ *
+ *   buildTraceparent() — NR → OTel active span → generate fresh IDs.
+ *     Used by producers (injectSnsAttributes, injectJobData) and the
+ *     Express/Fastify middleware at request start. Always returns a
+ *     traceparent so every message/request gets trace context.
  *
  * Edge cases covered:
- *   - NR not loaded: getTraceMetadata() returns undefined — we default to
- *     empty strings, buildTraceparent returns undefined, getTraceContext
- *     returns empty strings. No crash.
- *   - NR loaded but no active transaction: traceId/spanId are empty strings.
- *     buildTraceparent returns undefined. Consumers create a fresh trace.
- *   - Malformed traceparent (wrong number of parts, wrong hex lengths):
- *     extractParentContext returns ROOT_CONTEXT — consumer creates a fresh
- *     trace instead of crashing.
- *   - Flags field always set to 01 (sampled) on buildTraceparent because we
- *     want all async boundary crossings traced.
+ *   - NR's getTraceMetadata() can throw TypeError when the transaction is
+ *     null (pino-http fires after NR ends the transaction). Guarded with
+ *     try/catch.
+ *   - Malformed traceparent: extractParentContext returns ROOT_CONTEXT.
+ *   - Flags always 01 (sampled) on buildTraceparent.
  */
 import { type Context } from '@opentelemetry/api';
 import type { TraceContext } from './types';
-export declare function buildTraceparent(): string | undefined;
+/**
+ * Always returns a traceparent — from NR, OTel active span, or freshly
+ * generated. Used by producers to inject into SNS attributes / job data,
+ * and by the Express/Fastify middleware at request start.
+ */
+export declare function buildTraceparent(): string;
 export declare function extractParentContext(traceparent: string): Context;
+/**
+ * Returns trace context from active sources only (NR or OTel active span).
+ * Returns empty strings when neither is active — never generates fresh IDs.
+ * Used for log enrichment where fake IDs would create false correlations.
+ */
 export declare function getTraceContext(): TraceContext;
 export declare function getActiveContext(): Context;

package/dist/node-cliengo/src/trace-bridge.js

@@ -1,52 +1,81 @@
 "use strict";
 /**
- * W3C trace context bridge between New Relic and OpenTelemetry.
+ * W3C trace context utilities for New Relic and OpenTelemetry interop.
  *
  * Why this file exists:
- *   NR owns the active trace (it creates transactions via http monkey-patching),
- *   but our OTel spans need to share the same traceId so Foam and NR traces
- *   correlate. This module reads NR's trace metadata and converts it to/from
- *   W3C traceparent format (`00-{traceId}-{spanId}-{flags}`).
+ *   Reads trace context from two sources (NR first, then OTel's own active
+ *   span) and converts it to/from W3C traceparent format. This means trace
+ *   propagation works whether NR is installed, partially loaded, or completely
+ *   removed.
  *
- * Functions:
- *   - buildTraceparent(): reads NR's active traceId/spanId, returns a W3C
- *     traceparent string. Used by producers to inject into SNS attributes or
- *     BullMQ/Bull job data. Returns undefined when NR is not loaded or no
- *     active transaction exists.
- *   - extractParentContext(): parses a traceparent string into an OTel Context
- *     with a remote SpanContext. Used by consumers to link their OTel spans
- *     back to the producer's trace. Returns ROOT_CONTEXT on malformed input.
- *   - getTraceContext(): returns { traceId, spanId, traceparent } for log
- *     enrichment. Called lazily at log-write time (not at format creation time)
- *     so the trace context is always current.
+ * Two resolution modes:
+ *   resolveActiveTraceIds() — NR → OTel active span → empty strings.
+ *     Used by getTraceContext() (log enrichment) and createPinoMixin().
+ *     Never generates IDs — returns empty when no real source exists, so
+ *     it doesn't overwrite valid IDs injected by pino-http's customProps.
+ *
+ *   buildTraceparent() — NR → OTel active span → generate fresh IDs.
+ *     Used by producers (injectSnsAttributes, injectJobData) and the
+ *     Express/Fastify middleware at request start. Always returns a
+ *     traceparent so every message/request gets trace context.
  *
  * Edge cases covered:
- *   - NR not loaded: getTraceMetadata() returns undefined — we default to
- *     empty strings, buildTraceparent returns undefined, getTraceContext
- *     returns empty strings. No crash.
- *   - NR loaded but no active transaction: traceId/spanId are empty strings.
- *     buildTraceparent returns undefined. Consumers create a fresh trace.
- *   - Malformed traceparent (wrong number of parts, wrong hex lengths):
- *     extractParentContext returns ROOT_CONTEXT — consumer creates a fresh
- *     trace instead of crashing.
- *   - Flags field always set to 01 (sampled) on buildTraceparent because we
- *     want all async boundary crossings traced.
+ *   - NR's getTraceMetadata() can throw TypeError when the transaction is
+ *     null (pino-http fires after NR ends the transaction). Guarded with
+ *     try/catch.
+ *   - Malformed traceparent: extractParentContext returns ROOT_CONTEXT.
+ *   - Flags always 01 (sampled) on buildTraceparent.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildTraceparent = buildTraceparent;
 exports.extractParentContext = extractParentContext;
 exports.getTraceContext = getTraceContext;
 exports.getActiveContext = getActiveContext;
+const node_crypto_1 = require("node:crypto");
 const api_1 = require("@opentelemetry/api");
 const nr_1 = require("./nr");
+function generateTraceId() {
+    return (0, node_crypto_1.randomBytes)(16).toString('hex');
+}
+function generateSpanId() {
+    return (0, node_crypto_1.randomBytes)(8).toString('hex');
+}
+/**
+ * Resolves trace IDs from active sources only (NR or OTel active span).
+ * Returns empty strings when neither source has an active trace — never
+ * generates fresh IDs.
+ */
+function resolveActiveTraceIds() {
+    try {
+        const nr = (0, nr_1.getNr)();
+        const meta = nr.getTraceMetadata?.() ?? { traceId: '', spanId: '' };
+        if (meta.traceId && meta.spanId) {
+            return { traceId: meta.traceId, spanId: meta.spanId };
+        }
+    }
+    catch {
+        // NR transaction is null or getTraceMetadata threw
+    }
+    const activeSpan = api_1.trace.getActiveSpan();
+    if (activeSpan) {
+        const sc = activeSpan.spanContext();
+        if (sc.traceId && sc.spanId) {
+            return { traceId: sc.traceId, spanId: sc.spanId };
+        }
+    }
+    return { traceId: '', spanId: '' };
+}
+/**
+ * Always returns a traceparent — from NR, OTel active span, or freshly
+ * generated. Used by producers to inject into SNS attributes / job data,
+ * and by the Express/Fastify middleware at request start.
+ */
 function buildTraceparent() {
-    const nr = (0, nr_1.getNr)();
-    const meta = nr.getTraceMetadata?.() ?? { traceId: '', spanId: '' };
-    const { traceId, spanId } = meta;
-    if (!traceId || !spanId) {
-        return undefined;
+    const { traceId, spanId } = resolveActiveTraceIds();
+    if (traceId && spanId) {
+        return `00-${traceId}-${spanId}-01`;
     }
-    return `00-${traceId}-${spanId}-01`;
+    return `00-${generateTraceId()}-${generateSpanId()}-01`;
 }
 function extractParentContext(traceparent) {
     const parts = traceparent.split('-');
@@ -66,11 +95,13 @@ function extractParentContext(traceparent) {
     };
     return api_1.trace.setSpanContext(api_1.ROOT_CONTEXT, spanContext);
 }
+/**
+ * Returns trace context from active sources only (NR or OTel active span).
+ * Returns empty strings when neither is active — never generates fresh IDs.
+ * Used for log enrichment where fake IDs would create false correlations.
+ */
 function getTraceContext() {
-    const nr = (0, nr_1.getNr)();
-    const meta = nr.getTraceMetadata?.() ?? { traceId: '', spanId: '' };
-    const traceId = meta.traceId ?? '';
-    const spanId = meta.spanId ?? '';
+    const { traceId, spanId } = resolveActiveTraceIds();
     const traceparent = traceId && spanId ? `00-${traceId}-${spanId}-01` : '';
     return { traceId, spanId, traceparent };
 }

package/dist/node-cliengo/src/types.d.ts

@@ -2,8 +2,8 @@
  * All public interfaces and minimal type stubs for @foam/node-cliengo.
  *
  * Why this file exists:
- *   Defines every public type the library exposes (OtelBridge, InitOptions,
- *   TraceContext, BridgeMetrics) plus lightweight stubs for external frameworks
+ *   Defines every public type the library exposes (FoamInstance, InitOptions,
+ *   TraceContext, FoamMetrics) plus lightweight stubs for external frameworks
  *   (Express, Fastify, Winston, Pino, New Relic). These stubs exist so the
  *   library never imports framework types at the top level — services that only
  *   use Pino don't need Winston installed, and vice versa.
@@ -41,22 +41,19 @@ export interface TraceContext {
     spanId: string;
     traceparent: string;
 }
-export interface BridgeMetrics {
+export interface FoamMetrics {
     messageProcessingDuration: Histogram;
     messageProcessingErrors: Counter;
     messagesProcessed: Counter;
-    customHistogram(name: string, description: string, unit?: string): Histogram;
-    customCounter(name: string, description: string, unit?: string): Counter;
-    customGauge(name: string, description: string, unit?: string): ObservableGauge;
 }
-export interface OtelBridge {
+export interface FoamInstance {
     tracer: Tracer;
     meter: Meter;
     logger: LoggerProvider;
     traceProvider: BasicTracerProvider;
     meterProvider: MeterProvider;
     loggerProvider: LoggerProvider;
-    metrics: BridgeMetrics;
+    metrics: FoamMetrics;
     getTraceContext(): TraceContext;
     createExpressMiddleware(): ExpressRequestHandler;
     createExpressErrorHandler(): ExpressErrorHandler;
@@ -64,11 +61,14 @@ export interface OtelBridge {
     createWinstonFormat(): WinstonFormat;
     createWinstonTransport(): WinstonTransport;
     createPinoMixin(): () => Record<string, string>;
+    createPinoHttpOptions(): {
+        customProps: (req: any) => Record<string, string>;
+    };
     createPinoDestination(): NodeJS.WritableStream;
-    buildTraceparent(): string | undefined;
+    buildTraceparent(): string;
     injectSnsAttributes(attrs: Record<string, SnsMessageAttributeValue>): Record<string, SnsMessageAttributeValue>;
     injectJobData<T extends Record<string, unknown>>(data: T): T & {
-        traceparent?: string;
+        traceparent: string;
     };
     wrapSqsConsumer(tracer: Tracer, spanName: string, msg: SqsMessage, fn: () => Promise<void>): Promise<void>;
     wrapJobConsumer(tracer: Tracer, spanName: string, jobData: Record<string, unknown>, fn: () => Promise<void>): Promise<void>;

package/dist/node-cliengo/src/types.js

@@ -3,8 +3,8 @@
  * All public interfaces and minimal type stubs for @foam/node-cliengo.
  *
  * Why this file exists:
- *   Defines every public type the library exposes (OtelBridge, InitOptions,
- *   TraceContext, BridgeMetrics) plus lightweight stubs for external frameworks
+ *   Defines every public type the library exposes (FoamInstance, InitOptions,
+ *   TraceContext, FoamMetrics) plus lightweight stubs for external frameworks
  *   (Express, Fastify, Winston, Pino, New Relic). These stubs exist so the
  *   library never imports framework types at the top level — services that only
  *   use Pino don't need Winston installed, and vice versa.