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

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

@@ -1,5 +1,5 @@
 /**
- * Shared constants for the @foam/node-cliengo bridge.
+ * Shared constants for @foam/node-cliengo.
  *
  * Why this file exists:
  *   Centralizes all hardcoded values (endpoint, limits, redaction keys, health

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

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * Shared constants for the @foam/node-cliengo bridge.
+ * Shared constants for @foam/node-cliengo.
  *
  * Why this file exists:
  *   Centralizes all hardcoded values (endpoint, limits, redaction keys, health

package/dist/node-cliengo/src/http/express.d.ts

@@ -36,6 +36,27 @@
 import { type Tracer } from '@opentelemetry/api';
 import type { ExpressErrorHandler, ExpressRequestHandler } from '../types';
 export declare function createExpressMiddleware(tracer: Tracer): ExpressRequestHandler;
+/**
+ * Reads the trace context that was captured on the request at middleware time.
+ * Use this in pino-http's `customProps` to get trace IDs even after NR's
+ * transaction has ended:
+ *
+ *   pinoHttp({ customProps: (req) => getRequestTraceContext(req) })
+ */
+export declare function getRequestTraceContext(req: any): {
+    traceId: string;
+    spanId: string;
+    traceparent: string;
+};
+/**
+ * Returns pino-http options with customProps pre-wired to read the trace
+ * context stored on req by createExpressMiddleware(). Zero config for services:
+ *
+ *   app.use(pinoHttp({ logger, ...foam.createPinoHttpOptions() }));
+ */
+export declare function createPinoHttpOptions(): {
+    customProps: (req: any) => Record<string, string>;
+};
 export declare function createExpressErrorHandler(middlewareRef?: ExpressRequestHandler & {
     _markErrorHandler?: () => void;
 }): ExpressErrorHandler;

package/dist/node-cliengo/src/http/express.js

@@ -36,11 +36,14 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createExpressMiddleware = createExpressMiddleware;
+exports.getRequestTraceContext = getRequestTraceContext;
+exports.createPinoHttpOptions = createPinoHttpOptions;
 exports.createExpressErrorHandler = createExpressErrorHandler;
 const api_1 = require("@opentelemetry/api");
 const trace_bridge_1 = require("../trace-bridge");
 const request_context_1 = require("./request-context");
 const SPAN_KEY = Symbol.for('foam.shadow.span');
+const TRACE_CTX_KEY = Symbol.for('foam.trace.context');
 /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
 function createExpressMiddleware(tracer) {
     let errorHandlerRegistered = false;
@@ -52,15 +55,35 @@ function createExpressMiddleware(tracer) {
         const method = req.method ?? 'UNKNOWN';
         const target = req.originalUrl ?? req.url ?? '/';
         const { traceId, spanId } = (0, trace_bridge_1.getTraceContext)();
+        // Build a parent context so the shadow span shares the same OTel traceId
+        // as NR's transaction (or the active OTel span). Without this, startSpan()
+        // creates a root span with a separate traceId, breaking end-to-end
+        // traceability between HTTP spans, consumer spans, and logs.
+        let parentCtx;
+        if (traceId && spanId) {
+            parentCtx = api_1.trace.setSpanContext(api_1.ROOT_CONTEXT, {
+                traceId,
+                spanId,
+                traceFlags: 1,
+                isRemote: true,
+            });
+        }
         const span = tracer.startSpan(`${method} ${target}`, {
             attributes: {
                 'http.method': method,
                 'http.target': target,
-                ...(traceId ? { 'nr.traceId': traceId } : {}),
-                ...(spanId ? { 'nr.spanId': spanId } : {}),
             },
-        });
+        }, parentCtx);
         req[SPAN_KEY] = span;
+        // Read trace context from the span we just created — not from NR.
+        // The span's spanContext() always has the correct traceId, whether it
+        // inherited from NR or generated a fresh root.
+        const sc = span.spanContext();
+        req[TRACE_CTX_KEY] = {
+            traceId: sc.traceId,
+            spanId: sc.spanId,
+            traceparent: `00-${sc.traceId}-${sc.spanId}-01`,
+        };
         const startTime = Date.now();
         const onFinish = () => {
             try {
@@ -94,11 +117,47 @@ function createExpressMiddleware(tracer) {
             }
         };
         res.on('finish', onFinish);
-        next();
+        // Set the shadow span as the active context for the duration of the
+        // request. This makes it discoverable via trace.getActiveSpan() so
+        // buildTraceparent() (used by injectJobData/injectSnsAttributes) returns
+        // the same traceId — even without NR.
+        const activeCtx = api_1.trace.setSpan(parentCtx ?? api_1.ROOT_CONTEXT, span);
+        api_1.context.with(activeCtx, () => next());
     };
     middleware._markErrorHandler = markErrorHandlerRegistered;
     return middleware;
 }
+/**
+ * Reads the trace context that was captured on the request at middleware time.
+ * Use this in pino-http's `customProps` to get trace IDs even after NR's
+ * transaction has ended:
+ *
+ *   pinoHttp({ customProps: (req) => getRequestTraceContext(req) })
+ */
+function getRequestTraceContext(req) {
+    try {
+        const ctx = req[TRACE_CTX_KEY];
+        return {
+            traceId: ctx?.traceId ?? '',
+            spanId: ctx?.spanId ?? '',
+            traceparent: ctx?.traceparent ?? '',
+        };
+    }
+    catch {
+        return { traceId: '', spanId: '', traceparent: '' };
+    }
+}
+/**
+ * Returns pino-http options with customProps pre-wired to read the trace
+ * context stored on req by createExpressMiddleware(). Zero config for services:
+ *
+ *   app.use(pinoHttp({ logger, ...foam.createPinoHttpOptions() }));
+ */
+function createPinoHttpOptions() {
+    return {
+        customProps: (req) => getRequestTraceContext(req),
+    };
+}
 function createExpressErrorHandler(middlewareRef) {
     middlewareRef?._markErrorHandler?.();
     return (err, req, _res, next) => {

package/dist/node-cliengo/src/http/fastify.d.ts

@@ -25,4 +25,14 @@
  */
 import { type Tracer } from '@opentelemetry/api';
 import type { FastifyPluginAsync } from '../types';
+/**
+ * Reads the trace context that was captured on the request at hook time.
+ * Use this in Fastify's logger mixin or serializers to get trace IDs even
+ * after NR's transaction has ended.
+ */
+export declare function getRequestTraceContext(request: any): {
+    traceId: string;
+    spanId: string;
+    traceparent: string;
+};
 export declare function createFastifyPlugin(tracer: Tracer): FastifyPluginAsync;

package/dist/node-cliengo/src/http/fastify.js

@@ -25,12 +25,32 @@
  *   - done() always called even if our code throws — Fastify hook contract.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRequestTraceContext = getRequestTraceContext;
 exports.createFastifyPlugin = createFastifyPlugin;
 const api_1 = require("@opentelemetry/api");
 const trace_bridge_1 = require("../trace-bridge");
 const request_context_1 = require("./request-context");
 const SPAN_KEY = Symbol.for('foam.shadow.span');
 const START_KEY = Symbol.for('foam.shadow.start');
+const TRACE_CTX_KEY = Symbol.for('foam.trace.context');
+/**
+ * Reads the trace context that was captured on the request at hook time.
+ * Use this in Fastify's logger mixin or serializers to get trace IDs even
+ * after NR's transaction has ended.
+ */
+function getRequestTraceContext(request) {
+    try {
+        const ctx = request[TRACE_CTX_KEY];
+        return {
+            traceId: ctx?.traceId ?? '',
+            spanId: ctx?.spanId ?? '',
+            traceparent: ctx?.traceparent ?? '',
+        };
+    }
+    catch {
+        return { traceId: '', spanId: '', traceparent: '' };
+    }
+}
 /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
 function createFastifyPlugin(tracer) {
     return async (fastify) => {
@@ -39,22 +59,47 @@ function createFastifyPlugin(tracer) {
                 const method = request.method ?? 'UNKNOWN';
                 const url = request.url ?? '/';
                 const { traceId, spanId } = (0, trace_bridge_1.getTraceContext)();
+                let parentCtx;
+                if (traceId && spanId) {
+                    parentCtx = api_1.trace.setSpanContext(api_1.ROOT_CONTEXT, {
+                        traceId,
+                        spanId,
+                        traceFlags: 1,
+                        isRemote: true,
+                    });
+                }
                 const span = tracer.startSpan(`${method} ${url}`, {
                     attributes: {
                         'http.method': method,
                         'http.target': url,
-                        ...(traceId ? { 'nr.traceId': traceId } : {}),
-                        ...(spanId ? { 'nr.spanId': spanId } : {}),
                     },
-                });
+                }, parentCtx);
                 request[SPAN_KEY] = span;
                 request[START_KEY] = Date.now();
+                const sc = span.spanContext();
+                request[TRACE_CTX_KEY] = {
+                    traceId: sc.traceId,
+                    spanId: sc.spanId,
+                    traceparent: `00-${sc.traceId}-${sc.spanId}-01`,
+                };
             }
             catch {
                 /* never crash */
             }
             done();
         });
+        // Set the shadow span as the active context for route handlers so
+        // buildTraceparent() returns the same traceId — even without NR.
+        fastify.addHook('preHandler', (request, _reply, done) => {
+            const span = request[SPAN_KEY];
+            if (span) {
+                const activeCtx = api_1.trace.setSpan(api_1.ROOT_CONTEXT, span);
+                api_1.context.with(activeCtx, () => done());
+            }
+            else {
+                done();
+            }
+        });
         fastify.addHook('onError', (request, _reply, error, done) => {
             try {
                 const span = request[SPAN_KEY];

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

@@ -7,20 +7,20 @@
  *   (buildTraceparent, injectSnsAttributes, etc.), and all public types.
  *
  *   Most services only need: import { init } from '@foam/node-cliengo'
- *   Everything else is accessed via the returned OtelBridge object.
+ *   Everything else is accessed via the returned FoamInstance.
  *
  *   The individual function exports exist for tree-shaking and for cases where
  *   a service needs to call e.g. injectJobData() from a file that doesn't have
- *   access to the bridge instance.
+ *   access to the foam instance.
  */
 export { init } from './init';
 export { buildTraceparent, extractParentContext, getTraceContext } from './trace-bridge';
 export { injectSnsAttributes } from './sns';
 export { injectJobData, wrapJobConsumer } from './job';
 export { wrapSqsConsumer } from './sqs';
-export { createExpressMiddleware, createExpressErrorHandler } from './http/express';
-export { createFastifyPlugin } from './http/fastify';
+export { createExpressMiddleware, createExpressErrorHandler, getRequestTraceContext, createPinoHttpOptions } from './http/express';
+export { createFastifyPlugin, getRequestTraceContext as getFastifyRequestTraceContext } from './http/fastify';
 export { createWinstonFormat } from './logs/winston-format';
 export { createPinoMixin } from './logs/pino-mixin';
 export { FOAM_OTEL_ENDPOINT } from './constants';
-export type { BridgeMetrics, Counter, ExpressErrorHandler, ExpressRequestHandler, FastifyPluginAsync, Histogram, InitOptions, NewRelicAgent, ObservableGauge, OtelBridge, SnsMessageAttributeValue, SqsMessage, TraceContext, WinstonFormat, WinstonLogger, WinstonTransport, } from './types';
+export type { FoamMetrics, Counter, ExpressErrorHandler, ExpressRequestHandler, FastifyPluginAsync, Histogram, InitOptions, NewRelicAgent, ObservableGauge, FoamInstance, SnsMessageAttributeValue, SqsMessage, TraceContext, WinstonFormat, WinstonLogger, WinstonTransport, } from './types';

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

@@ -8,14 +8,14 @@
  *   (buildTraceparent, injectSnsAttributes, etc.), and all public types.
  *
  *   Most services only need: import { init } from '@foam/node-cliengo'
- *   Everything else is accessed via the returned OtelBridge object.
+ *   Everything else is accessed via the returned FoamInstance.
  *
  *   The individual function exports exist for tree-shaking and for cases where
  *   a service needs to call e.g. injectJobData() from a file that doesn't have
- *   access to the bridge instance.
+ *   access to the foam instance.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FOAM_OTEL_ENDPOINT = exports.createPinoMixin = exports.createWinstonFormat = exports.createFastifyPlugin = exports.createExpressErrorHandler = exports.createExpressMiddleware = exports.wrapSqsConsumer = exports.wrapJobConsumer = exports.injectJobData = exports.injectSnsAttributes = exports.getTraceContext = exports.extractParentContext = exports.buildTraceparent = exports.init = void 0;
+exports.FOAM_OTEL_ENDPOINT = exports.createPinoMixin = exports.createWinstonFormat = exports.getFastifyRequestTraceContext = exports.createFastifyPlugin = exports.createPinoHttpOptions = exports.getRequestTraceContext = exports.createExpressErrorHandler = exports.createExpressMiddleware = exports.wrapSqsConsumer = exports.wrapJobConsumer = exports.injectJobData = exports.injectSnsAttributes = exports.getTraceContext = exports.extractParentContext = exports.buildTraceparent = exports.init = void 0;
 var init_1 = require("./init");
 Object.defineProperty(exports, "init", { enumerable: true, get: function () { return init_1.init; } });
 var trace_bridge_1 = require("./trace-bridge");
@@ -32,8 +32,11 @@ Object.defineProperty(exports, "wrapSqsConsumer", { enumerable: true, get: funct
 var express_1 = require("./http/express");
 Object.defineProperty(exports, "createExpressMiddleware", { enumerable: true, get: function () { return express_1.createExpressMiddleware; } });
 Object.defineProperty(exports, "createExpressErrorHandler", { enumerable: true, get: function () { return express_1.createExpressErrorHandler; } });
+Object.defineProperty(exports, "getRequestTraceContext", { enumerable: true, get: function () { return express_1.getRequestTraceContext; } });
+Object.defineProperty(exports, "createPinoHttpOptions", { enumerable: true, get: function () { return express_1.createPinoHttpOptions; } });
 var fastify_1 = require("./http/fastify");
 Object.defineProperty(exports, "createFastifyPlugin", { enumerable: true, get: function () { return fastify_1.createFastifyPlugin; } });
+Object.defineProperty(exports, "getFastifyRequestTraceContext", { enumerable: true, get: function () { return fastify_1.getRequestTraceContext; } });
 var winston_format_1 = require("./logs/winston-format");
 Object.defineProperty(exports, "createWinstonFormat", { enumerable: true, get: function () { return winston_format_1.createWinstonFormat; } });
 var pino_mixin_1 = require("./logs/pino-mixin");

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

@@ -1,40 +1,43 @@
 /**
- * Main entry point — init() creates the OtelBridge singleton for a service.
+ * Main entry point — init() creates the Foam singleton for a service.
  *
  * Why this file exists:
  *   Orchestrates all three OTel signals (traces, logs, metrics) into a single
- *   init() call that returns an OtelBridge object. Services call init() once at
- *   startup and use the returned bridge for everything else. The bridge is
+ *   init() call that returns a FoamInstance. Services call init() once at
+ *   startup and use the returned instance for everything else. It is
  *   designed to coexist with New Relic APM without touching NR's globals.
  *
  * Two-gate system:
- *   1. Kill switch (FOAM_OTEL_ENABLED): if false, returns a fully inert bridge.
+ *   1. Kill switch (FOAM_OTEL_ENABLED): if false, returns a fully inert instance.
  *      Every API exists but does nothing — zero overhead, zero network, zero risk.
  *      This is the master emergency shutoff.
  *   2. Production gate (NODE_ENV): exporters are only attached when NODE_ENV is
- *      "production" (or forceExport is true). In dev/test, the bridge is fully
+ *      "production" (or forceExport is true). In dev/test, Foam is fully
  *      functional (trace propagation, log enrichment work) but nothing is sent
  *      to Foam. Developers without FOAM_OTEL_TOKEN get no crashes.
  *
  * Edge cases covered:
- *   - Double init(): logs a warning, returns the existing bridge (singleton
+ *   - Double init(): logs a warning, returns the existing instance (singleton
  *     per service name). Prevents duplicate providers/processors/handlers.
  *   - Token undefined in dev: silently accepted — no OTLP export anyway.
  *   - Token undefined in prod: logs warning, disables exporters. All other
  *     features (trace propagation, log enrichment, NR bridging) still work.
  *   - Token undefined + forceExport: throws (fail-fast — you asked to force
  *     export but provided no credentials).
+ *   - Custom endpoint without forceExport: throws. Production always uses the
+ *     default Foam endpoint; custom endpoints are only for dev/staging.
  *   - Auto-shutdown (SIGTERM/SIGINT): flushes all providers with 5s timeout,
  *     then calls process.exit(0). Without the explicit exit, registering
  *     process.on('SIGTERM') replaces Node's default terminate behavior — services
  *     without their own handler (gpt-intentions, cb-proxy) would hang forever.
  *   - Manual shutdown: services with ordered cleanup (hsm-backend, kori, combee)
- *     pass autoShutdown: false and call bridge.shutdown() in their own handler.
+ *     pass autoShutdown: false and call foam.shutdown() in their own handler.
  *   - shutdown() is idempotent — safe to call multiple times.
  *   - Process exception handlers use process.on() (not .once()) so they don't
  *     replace NR's or Winston's existing handlers. All handlers fire independently.
- *   - uncaughtException handler flushes via shutdown() — best effort to get the
- *     fatal log to Foam before the process dies. Never calls process.exit().
+ *   - uncaughtException/unhandledRejection create short-lived spans with
+ *     recordException() so they appear in otel_traces, then force-flush the
+ *     trace provider before shutdown. Never calls process.exit().
  *   - Winston auto-wiring: init({ winston: baseLogger }) calls logger.add() for
  *     the OTLP transport and rewrites logger.format to prepend trace enrichment.
  *     Both work post-construction. Avoids circular deps (main.ts imports logger,
@@ -46,5 +49,5 @@
  *     are NEVER registered globally (.register() never called). NR owns the
  *     global registrations.
  */
-import type { InitOptions, OtelBridge } from './types';
-export declare function init(serviceName: string, token?: string, options?: InitOptions): OtelBridge;
+import type { InitOptions, FoamInstance } from './types';
+export declare function init(serviceName: string, token?: string, options?: InitOptions): FoamInstance;

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

@@ -1,41 +1,44 @@
 "use strict";
 /**
- * Main entry point — init() creates the OtelBridge singleton for a service.
+ * Main entry point — init() creates the Foam singleton for a service.
  *
  * Why this file exists:
  *   Orchestrates all three OTel signals (traces, logs, metrics) into a single
- *   init() call that returns an OtelBridge object. Services call init() once at
- *   startup and use the returned bridge for everything else. The bridge is
+ *   init() call that returns a FoamInstance. Services call init() once at
+ *   startup and use the returned instance for everything else. It is
  *   designed to coexist with New Relic APM without touching NR's globals.
  *
  * Two-gate system:
- *   1. Kill switch (FOAM_OTEL_ENABLED): if false, returns a fully inert bridge.
+ *   1. Kill switch (FOAM_OTEL_ENABLED): if false, returns a fully inert instance.
  *      Every API exists but does nothing — zero overhead, zero network, zero risk.
  *      This is the master emergency shutoff.
  *   2. Production gate (NODE_ENV): exporters are only attached when NODE_ENV is
- *      "production" (or forceExport is true). In dev/test, the bridge is fully
+ *      "production" (or forceExport is true). In dev/test, Foam is fully
  *      functional (trace propagation, log enrichment work) but nothing is sent
  *      to Foam. Developers without FOAM_OTEL_TOKEN get no crashes.
  *
  * Edge cases covered:
- *   - Double init(): logs a warning, returns the existing bridge (singleton
+ *   - Double init(): logs a warning, returns the existing instance (singleton
  *     per service name). Prevents duplicate providers/processors/handlers.
  *   - Token undefined in dev: silently accepted — no OTLP export anyway.
  *   - Token undefined in prod: logs warning, disables exporters. All other
  *     features (trace propagation, log enrichment, NR bridging) still work.
  *   - Token undefined + forceExport: throws (fail-fast — you asked to force
  *     export but provided no credentials).
+ *   - Custom endpoint without forceExport: throws. Production always uses the
+ *     default Foam endpoint; custom endpoints are only for dev/staging.
  *   - Auto-shutdown (SIGTERM/SIGINT): flushes all providers with 5s timeout,
  *     then calls process.exit(0). Without the explicit exit, registering
  *     process.on('SIGTERM') replaces Node's default terminate behavior — services
  *     without their own handler (gpt-intentions, cb-proxy) would hang forever.
  *   - Manual shutdown: services with ordered cleanup (hsm-backend, kori, combee)
- *     pass autoShutdown: false and call bridge.shutdown() in their own handler.
+ *     pass autoShutdown: false and call foam.shutdown() in their own handler.
  *   - shutdown() is idempotent — safe to call multiple times.
  *   - Process exception handlers use process.on() (not .once()) so they don't
  *     replace NR's or Winston's existing handlers. All handlers fire independently.
- *   - uncaughtException handler flushes via shutdown() — best effort to get the
- *     fatal log to Foam before the process dies. Never calls process.exit().
+ *   - uncaughtException/unhandledRejection create short-lived spans with
+ *     recordException() so they appear in otel_traces, then force-flush the
+ *     trace provider before shutdown. Never calls process.exit().
  *   - Winston auto-wiring: init({ winston: baseLogger }) calls logger.add() for
  *     the OTLP transport and rewrites logger.format to prepend trace enrichment.
  *     Both work post-construction. Avoids circular deps (main.ts imports logger,
@@ -49,7 +52,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.init = init;
-const api_logs_1 = require("@opentelemetry/api-logs");
+const api_1 = require("@opentelemetry/api");
 const exporter_logs_otlp_http_1 = require("@opentelemetry/exporter-logs-otlp-http");
 const exporter_metrics_otlp_http_1 = require("@opentelemetry/exporter-metrics-otlp-http");
 const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
@@ -71,15 +74,15 @@ const nr_1 = require("./nr");
 const sns_1 = require("./sns");
 const sqs_1 = require("./sqs");
 const trace_bridge_1 = require("./trace-bridge");
-const bridges = new Map();
-function createInertBridge(serviceName) {
+const instances = new Map();
+function createInertInstance(serviceName) {
     const resource = (0, resources_1.resourceFromAttributes)({ 'service.name': serviceName });
     const traceProvider = new sdk_trace_base_1.BasicTracerProvider({ resource });
     const loggerProvider = new sdk_logs_1.LoggerProvider({ resource });
     const meterProvider = new sdk_metrics_1.MeterProvider({ resource });
     const tracer = traceProvider.getTracer(serviceName);
     const meter = meterProvider.getMeter(serviceName);
-    const metrics = (0, instruments_1.createBridgeMetrics)(meterProvider, serviceName);
+    const metrics = (0, instruments_1.createFoamMetrics)(meterProvider, serviceName);
     return {
         tracer,
         meter,
@@ -97,12 +100,13 @@ function createInertBridge(serviceName) {
         }),
         createWinstonTransport: () => ({}),
         createPinoMixin: () => () => ({}),
+        createPinoHttpOptions: () => ({ customProps: () => ({}) }),
         createPinoDestination: () => new node_stream_1.Writable({
             write: (_c, _e, cb) => cb(),
         }),
-        buildTraceparent: () => undefined,
-        injectSnsAttributes: (attrs) => attrs,
-        injectJobData: (data) => data,
+        buildTraceparent: trace_bridge_1.buildTraceparent,
+        injectSnsAttributes: sns_1.injectSnsAttributes,
+        injectJobData: job_1.injectJobData,
         wrapSqsConsumer: async (_t, _s, _m, fn) => fn(),
         wrapJobConsumer: async (_t, _s, _j, fn) => fn(),
         extractParentContext: () => {
@@ -114,19 +118,19 @@ function createInertBridge(serviceName) {
 }
 /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call */
 function init(serviceName, token, options = {}) {
-    const existing = bridges.get(serviceName);
+    const existing = instances.get(serviceName);
     if (existing) {
         // eslint-disable-next-line no-console
-        console.warn(`[foam] init() already called for "${serviceName}" — returning existing bridge`);
+        console.warn(`[foam] init() already called for "${serviceName}" — returning existing instance`);
         return existing;
     }
     // Kill switch
     const isEnabled = (options.enabled ??
         ((process.env.FOAM_OTEL_ENABLED ?? 'true').toLowerCase() === 'true')) === true;
     if (!isEnabled) {
-        const bridge = createInertBridge(serviceName);
-        bridges.set(serviceName, bridge);
-        return bridge;
+        const foam = createInertInstance(serviceName);
+        instances.set(serviceName, foam);
+        return foam;
     }
     // Resolve NR
     (0, nr_1.resolveNewRelic)(options.newrelic);
@@ -143,6 +147,9 @@ function init(serviceName, token, options = {}) {
     }
     const hasToken = Boolean(token);
     const canExport = shouldExport && hasToken;
+    if (options.endpoint && !options.forceExport) {
+        throw new Error('[foam] custom endpoint requires forceExport: true — production always uses the default Foam endpoint');
+    }
     const endpoint = options.endpoint ?? constants_1.FOAM_OTEL_ENDPOINT;
     const resource = (0, resources_1.resourceFromAttributes)({ 'service.name': serviceName });
     const authHeaders = token
@@ -193,7 +200,7 @@ function init(serviceName, token, options = {}) {
     });
     const tracer = traceProvider.getTracer(serviceName);
     const meter = meterProvider.getMeter(serviceName);
-    const metrics = (0, instruments_1.createBridgeMetrics)(meterProvider, serviceName);
+    const metrics = (0, instruments_1.createFoamMetrics)(meterProvider, serviceName);
     let _isShutdown = false;
     const shutdown = async () => {
         if (_isShutdown) {
@@ -217,41 +224,41 @@ function init(serviceName, token, options = {}) {
         process.on('SIGTERM', () => void handler());
         process.on('SIGINT', () => void handler());
     }
-    // Process-level exception capture
-    const otelLogger = loggerProvider.getLogger(serviceName);
+    // Process-level exception capture — recorded as span exceptions so they
+    // land in otel_traces (not otel_logs). Each creates a short-lived span,
+    // records the exception, ends it, then force-flushes the trace provider.
     process.on('uncaughtException', (err) => {
         try {
-            otelLogger.emit({
-                body: err.message,
-                severityNumber: api_logs_1.SeverityNumber.FATAL,
-                severityText: 'FATAL',
-                attributes: {
-                    'exception.type': err.constructor.name,
-                    'exception.message': err.message,
-                    'exception.stacktrace': err.stack ?? '',
-                    'process.event': 'uncaughtException',
-                },
+            const span = tracer.startSpan('uncaughtException', {
+                attributes: { 'process.event': 'uncaughtException' },
             });
-            void shutdown();
+            span.recordException({
+                name: err.constructor.name,
+                message: err.message,
+                stack: err.stack,
+            });
+            span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: err.message });
+            span.end();
+            void traceProvider.forceFlush().then(() => shutdown());
         }
         catch {
-            /* best effort */
+            void shutdown();
         }
     });
     process.on('unhandledRejection', (reason) => {
         try {
             const err = reason instanceof Error ? reason : new Error(String(reason));
-            otelLogger.emit({
-                body: err.message,
-                severityNumber: api_logs_1.SeverityNumber.ERROR,
-                severityText: 'ERROR',
-                attributes: {
-                    'exception.type': err.constructor.name,
-                    'exception.message': err.message,
-                    'exception.stacktrace': err.stack ?? '',
-                    'process.event': 'unhandledRejection',
-                },
+            const span = tracer.startSpan('unhandledRejection', {
+                attributes: { 'process.event': 'unhandledRejection' },
+            });
+            span.recordException({
+                name: err.constructor.name,
+                message: err.message,
+                stack: err.stack,
             });
+            span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: err.message });
+            span.end();
+            void traceProvider.forceFlush();
         }
         catch {
             /* best effort */
@@ -318,7 +325,7 @@ function init(serviceName, token, options = {}) {
         }
     }
     const expressMiddleware = (0, express_1.createExpressMiddleware)(tracer);
-    const bridge = {
+    const foam = {
         tracer,
         meter,
         logger: loggerProvider,
@@ -333,6 +340,7 @@ function init(serviceName, token, options = {}) {
         createWinstonFormat: () => (0, winston_format_1.createWinstonFormat)(),
         createWinstonTransport: () => (0, winston_transport_1.createWinstonTransport)(loggerProvider, serviceName),
         createPinoMixin: () => (0, pino_mixin_1.createPinoMixin)(),
+        createPinoHttpOptions: () => (0, express_1.createPinoHttpOptions)(),
         createPinoDestination: () => (0, pino_destination_1.createPinoDestination)(loggerProvider, serviceName),
         buildTraceparent: trace_bridge_1.buildTraceparent,
         injectSnsAttributes: sns_1.injectSnsAttributes,
@@ -342,7 +350,7 @@ function init(serviceName, token, options = {}) {
         extractParentContext: trace_bridge_1.extractParentContext,
         shutdown,
     };
-    bridges.set(serviceName, bridge);
-    return bridge;
+    instances.set(serviceName, foam);
+    return foam;
 }
 /* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call */

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

@@ -24,8 +24,8 @@
  *     consistent exception recording.
  */
 import { type Tracer } from '@opentelemetry/api';
-import type { BridgeMetrics } from './types';
+import type { FoamMetrics } from './types';
 export declare function injectJobData<T extends Record<string, unknown>>(data: T): T & {
-    traceparent?: string;
+    traceparent: string;
 };
-export declare function wrapJobConsumer(tracer: Tracer, spanName: string, jobData: Record<string, unknown>, fn: () => Promise<void>, metrics?: BridgeMetrics): Promise<void>;
+export declare function wrapJobConsumer(tracer: Tracer, spanName: string, jobData: Record<string, unknown>, fn: () => Promise<void>, metrics?: FoamMetrics): Promise<void>;

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

@@ -31,11 +31,7 @@ const api_1 = require("@opentelemetry/api");
 const nr_1 = require("./nr");
 const trace_bridge_1 = require("./trace-bridge");
 function injectJobData(data) {
-    const tp = (0, trace_bridge_1.buildTraceparent)();
-    if (!tp) {
-        return data;
-    }
-    return { ...data, traceparent: tp };
+    return { ...data, traceparent: (0, trace_bridge_1.buildTraceparent)() };
 }
 async function wrapJobConsumer(tracer, spanName, jobData, fn, metrics) {
     const nr = (0, nr_1.getNr)();

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

@@ -21,8 +21,13 @@
  *     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).