mercury-composable 4.12.1 → 4.12.15

package/README.md

@@ -14,7 +14,12 @@ This package is a deliberately **lightweight wrapper of the Event-over-HTTP prot
 - a **primitive in-process event bus** — the single dispatch pipeline: one FIFO mailbox
   per route consumed by `instances` worker loops, and
 - the **minimalist utilities** shared with the engines for consistency: configuration
-  management, logging in the engines' presentation format, and distributed-trace context.
+  management, logging in the engines' presentation format, and distributed-trace context, and
+- the **OpenTelemetry forwarder** (opt-in, `otel.forwarding=true`): the host's trace spans
+  exported over OTLP/HTTP to Dynatrace, Splunk or a collector — no SDK, no new dependency, and
+- the **AI nodes** `llm.chat` / `llm.stream` in the demo (`examples/llm-nodes.mjs`): provider-neutral
+  Gemini and Anthropic adapters over their REST APIs through `fetch` — the graph decides, the model
+  advises; `llm.stream` relays the provider's real token stream progressively.
 
 Orchestration deliberately stays in the engines. Functions written here are addressed by
 route name through the engines' declarative `yaml.event.over.http` map, so a flow or a
@@ -24,10 +29,12 @@ graph task calls a Node.js function exactly as if it were local.
 [AI Agent Guide](https://accenture.github.io/mercury-nodejs/guides/ai-agent-guide/)
 for deterministic function generation.
 
-> **Status: pre-release.** This repository was repurposed in August 2026 for the polyglot
-> initiative: instead of re-porting the full composable foundation to Node.js, the fresh
-> start rides the engines' Event-over-HTTP protocol — light by design. The previous
-> Node.js port (up to v4.3.28) remains available in the git history and on npm.
+> **Published on npm.** `mercury-composable` v4.12.15 is live —
+> `npm install mercury-composable`. This repository was repurposed in August 2026 for the
+> polyglot initiative: instead of re-porting the full composable foundation to Node.js, the
+> fresh start rides the engines' Event-over-HTTP protocol — light by design. The previous
+> Node.js port (up to v4.3.28) remains available in the git history only — it never
+> occupied this name on the public registry.
 
 ## Quick start
 
@@ -48,8 +55,8 @@ await platform.run(); // port from rest.server.port (default 8085)
 Run it:
 
 ```bash
-npm install && npm run build
-node dist/src/cli.js app.mjs -Drest.server.port=8087     # or: mercury-serve app.mjs -Drest.server.port=8087
+npm install mercury-composable
+mercury-serve app.mjs -Drest.server.port=8087
 ```
 
 Call it from a Mercury engine application with two configuration entries and no code —

package/dist/src/bus.d.ts

@@ -96,7 +96,7 @@ export declare class EventBus {
     close(): void;
     private runWorker;
     /** Run the handler under its trace context and shape the outcome as a reply. */
-    private static execute;
+    private execute;
     /**
      * Run an interceptor handler: it receives the raw envelope, replies
      * manually through reply_to (the engines' EventInterceptor contract), and
@@ -105,6 +105,13 @@ export declare class EventBus {
      * sink sees it - and a streaming host renders it in-band.
      */
     private executeInterceptor;
+    /**
+     * Hand an emitted dataset to the engines' extension route when a function is
+     * registered there (the OpenTelemetry forwarder, or an application's own): a
+     * drop-n-forget envelope routed like a reply, carrying no trace - so the
+     * forwarder's own execution emits no dataset, the engines' zero-tracing forwarder.
+     */
+    private forward;
     private replyInterceptorError;
 }
 export {};

package/dist/src/bus.js

@@ -37,7 +37,7 @@ import { AppException } from './exceptions.js';
 import { getLogger } from './log.js';
 import { randomBytes } from 'node:crypto';
 import { appOrigin } from './actuator.js';
-import { MY_CID_TAG, MY_CORRELATION_ID, RPC_TAG, runWithTrace } from './trace.js';
+import { DISTRIBUTED_TRACE_FORWARDER, MY_CID_TAG, MY_CORRELATION_ID, RPC_TAG, runWithTrace } from './trace.js';
 const log = getLogger('mercury.bus');
 /** An RPC delivery missed its deadline; adapters shape the 408 for their protocol. */
 export class DeliveryTimeout extends Error {
@@ -106,7 +106,7 @@ function isRpc(delivery) {
  */
 function emitTrace(delivery, info, start, execTime, status, success, exception) {
     if (!info.traceId || isRpc(delivery)) {
-        return;
+        return undefined;
     }
     const trace = {
         origin: appOrigin(),
@@ -133,6 +133,7 @@ function emitTrace(delivery, info, start, execTime, status, success, exception)
         dataset.annotations = { ...info.annotations };
     }
     telemetryLog.info(dataset);
+    return dataset;
 }
 const CLOSED = Symbol('bus-closed');
 /** Unbounded FIFO handing items to awaiting consumers (node's missing asyncio.Queue). */
@@ -285,7 +286,7 @@ export class EventBus {
             }
             const reply = delivery.service.interceptor
                 ? await this.executeInterceptor(delivery)
-                : await EventBus.execute(delivery);
+                : await this.execute(delivery);
             if (delivery.resolve) {
                 if (!delivery.settled) {
                     delivery.settled = true;
@@ -299,7 +300,7 @@ export class EventBus {
         }
     }
     /** Run the handler under its trace context and shape the outcome as a reply. */
-    static async execute(delivery) {
+    async execute(delivery) {
         const myCid = businessCid(delivery);
         const headers = headersView(delivery, myCid);
         const info = traceInfoOf(delivery, myCid);
@@ -329,7 +330,7 @@ export class EventBus {
         if (Object.keys(info.annotations).length) {
             reply.annotations = { ...info.annotations, ...reply.annotations };
         }
-        emitTrace(delivery, info, startIso, reply.execTime, reply.getStatus(), !reply.hasError(), reply.hasError() ? String(reply.body) : undefined);
+        this.forward(emitTrace(delivery, info, startIso, reply.execTime, reply.getStatus(), !reply.hasError(), reply.hasError() ? String(reply.body) : undefined));
         return reply;
     }
     /**
@@ -357,10 +358,22 @@ export class EventBus {
         }
         const status = error instanceof AppException ? error.status : (error ? 500 : 200);
         const execTime = Math.round(Number(process.hrtime.bigint() - start) / 1000) / 1000;
-        emitTrace(delivery, info, startIso, execTime, status, !error, error ? String(error.message ?? error) : undefined);
+        this.forward(emitTrace(delivery, info, startIso, execTime, status, !error, error ? String(error.message ?? error) : undefined));
         // an interceptor's own outcome is never auto-replied
         return new EventEnvelope();
     }
+    /**
+     * Hand an emitted dataset to the engines' extension route when a function is
+     * registered there (the OpenTelemetry forwarder, or an application's own): a
+     * drop-n-forget envelope routed like a reply, carrying no trace - so the
+     * forwarder's own execution emits no dataset, the engines' zero-tracing forwarder.
+     */
+    forward(dataset) {
+        if (!dataset || !this.router) {
+            return;
+        }
+        this.router(new EventEnvelope(DISTRIBUTED_TRACE_FORWARDER, dataset));
+    }
     replyInterceptorError(route, event, e) {
         let error;
         if (e instanceof AppException) {

package/dist/src/index.d.ts

@@ -19,6 +19,7 @@ export { getLogger, Logger } from './log.js';
 export { defaultRegistry, FunctionRegistry, preload, validateRoute } from './registry.js';
 export type { Handler, ServiceDef } from './registry.js';
 export { EventApiServer, Platform, platform } from './server.js';
-export { annotateTrace, getTrace, runWithTrace, updateContext } from './trace.js';
+export * as otel from './otel/index.js';
+export { annotateTrace, DISTRIBUTED_TRACE_FORWARDER, getTrace, runWithTrace, updateContext } from './trace.js';
 export type { TraceInfo } from './trace.js';
 export { VERSION } from './version.js';

package/dist/src/index.js

@@ -17,5 +17,6 @@ export { AppException, CompactFormatError } from './exceptions.js';
 export { getLogger, Logger } from './log.js';
 export { defaultRegistry, FunctionRegistry, preload, validateRoute } from './registry.js';
 export { EventApiServer, Platform, platform } from './server.js';
-export { annotateTrace, getTrace, runWithTrace, updateContext } from './trace.js';
+export * as otel from './otel/index.js';
+export { annotateTrace, DISTRIBUTED_TRACE_FORWARDER, getTrace, runWithTrace, updateContext } from './trace.js';
 export { VERSION } from './version.js';

package/dist/src/otel/config.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The forwarder's configuration: the engines' `otel.*` keys, read the engines'
+ * way (the Rust port's `config.rs` and `headers.rs`).
+ *
+ * | Key | Meaning | Default |
+ * |-----|---------|---------|
+ * | `otel.forwarding` | the master switch | `false` |
+ * | `otel.exporter.otlp.endpoint` | the OTLP/HTTP traces URL incl. the signal path | `http://localhost:4318/v1/traces` |
+ * | `otel.exporter.otlp.timeout` | per-export timeout, milliseconds | `10000` |
+ * | `otel.exporter.otlp.connect.timeout` | no effect here (fetch has one overall timeout) | - |
+ * | `otel.exporter.otlp.headers` | request headers: `k=v` or `k: v`, comma list | (none) |
+ * | `otel.exporter.otlp.compression` | only `none` is honoured (a warning otherwise) | `none` |
+ * | `otel.service.name` | the `service.name` resource attribute | `application.name` |
+ */
+import type { AppConfig } from '../config.js';
+export declare const FORWARDING_SWITCH = "otel.forwarding";
+export declare const ENDPOINT = "otel.exporter.otlp.endpoint";
+export declare const TIMEOUT = "otel.exporter.otlp.timeout";
+export declare const CONNECT_TIMEOUT = "otel.exporter.otlp.connect.timeout";
+export declare const COMPRESSION = "otel.exporter.otlp.compression";
+export declare const HEADERS = "otel.exporter.otlp.headers";
+export declare const SERVICE_NAME = "otel.service.name";
+export declare const DEFAULT_ENDPOINT = "http://localhost:4318/v1/traces";
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+export declare const DEFAULT_COMPRESSION = "none";
+export declare const DEFAULT_SERVICE = "mercury";
+/** The request headers, resolved per export. */
+export type HeaderSupplier = () => Array<[string, string]>;
+export interface ForwarderSettings {
+    endpoint: string;
+    serviceName: string;
+    scopeVersion: string;
+    timeoutMs: number;
+    compression: string;
+    headers: HeaderSupplier;
+}
+/**
+ * Read the `otel.*` keys. Infallible: an unparseable number falls back to its
+ * default with a warning; the endpoint URL is validated when the exporter is built.
+ */
+export declare function settingsFromConfig(config: AppConfig): ForwarderSettings;
+/** Settings with a FIXED header list - for tests and callers whose credentials are known up front. */
+export declare function fixedSettings(endpoint: string, options?: {
+    timeoutMs?: number;
+    headers?: Array<[string, string]>;
+    serviceName?: string;
+}): ForwarderSettings;
+/**
+ * A supplier that re-parses the raw header setting on every call and announces
+ * the header NAMES once when they first resolve (never values).
+ */
+export declare function reloadingHeaders(raw: () => string | undefined): HeaderSupplier;
+/**
+ * The OpenTelemetry `key=value,key2=value2` list, also accepting the `key: value`
+ * form; the FIRST separator splits, so a token containing `=` or `:` survives; a
+ * repeated name keeps its last value.
+ */
+export declare function parseHeaders(raw: string | undefined): Array<[string, string]>;

package/dist/src/otel/config.js

@@ -0,0 +1,119 @@
+import { getLogger } from '../log.js';
+import { VERSION } from '../version.js';
+const log = getLogger('mercury.otel');
+export const FORWARDING_SWITCH = 'otel.forwarding';
+export const ENDPOINT = 'otel.exporter.otlp.endpoint';
+export const TIMEOUT = 'otel.exporter.otlp.timeout';
+export const CONNECT_TIMEOUT = 'otel.exporter.otlp.connect.timeout';
+export const COMPRESSION = 'otel.exporter.otlp.compression';
+export const HEADERS = 'otel.exporter.otlp.headers';
+export const SERVICE_NAME = 'otel.service.name';
+const APP_NAME = 'application.name';
+const APP_VERSION = 'info.app.version';
+export const DEFAULT_ENDPOINT = 'http://localhost:4318/v1/traces';
+export const DEFAULT_TIMEOUT_MS = 10_000;
+export const DEFAULT_COMPRESSION = 'none';
+export const DEFAULT_SERVICE = 'mercury';
+/**
+ * Read the `otel.*` keys. Infallible: an unparseable number falls back to its
+ * default with a warning; the endpoint URL is validated when the exporter is built.
+ */
+export function settingsFromConfig(config) {
+    const serviceName = config.getProperty(SERVICE_NAME) ?? config.getProperty(APP_NAME)
+        ?? DEFAULT_SERVICE;
+    const endpoint = config.getProperty(ENDPOINT) ?? DEFAULT_ENDPOINT;
+    const timeoutMs = millis(config.getProperty(TIMEOUT), TIMEOUT, DEFAULT_TIMEOUT_MS);
+    const compression = (config.getProperty(COMPRESSION) ?? '').trim() || DEFAULT_COMPRESSION;
+    if (compression.toLowerCase() !== DEFAULT_COMPRESSION) {
+        log.warn(`${COMPRESSION}=${compression} is not supported by this host - exporting ` +
+            'uncompressed (the payload is one span per request); set none to silence this');
+    }
+    if (config.exists(CONNECT_TIMEOUT)) {
+        log.warn(`${CONNECT_TIMEOUT} has no effect on this host - ${TIMEOUT} bounds the whole ` +
+            'export, connect included');
+    }
+    const scopeVersion = config.getProperty(APP_VERSION) ?? VERSION;
+    // read through a supplier so a credential published AFTER this start-up read
+    // (a runtime override, the engines' -D / config.set analog a credential
+    // bootstrap uses) is picked up rather than frozen out
+    const headers = reloadingHeaders(() => config.getProperty(HEADERS));
+    return { endpoint, serviceName, scopeVersion, timeoutMs, compression, headers };
+}
+/** Settings with a FIXED header list - for tests and callers whose credentials are known up front. */
+export function fixedSettings(endpoint, options = {}) {
+    const fixed = [...(options.headers ?? [])];
+    return {
+        endpoint,
+        serviceName: options.serviceName ?? DEFAULT_SERVICE,
+        scopeVersion: VERSION,
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        compression: DEFAULT_COMPRESSION,
+        headers: () => [...fixed]
+    };
+}
+/**
+ * A supplier that re-parses the raw header setting on every call and announces
+ * the header NAMES once when they first resolve (never values).
+ */
+export function reloadingHeaders(raw) {
+    let announced = false;
+    return () => {
+        const headers = parseHeaders(raw());
+        if (headers.length && !announced) {
+            announced = true;
+            log.info(`OTLP credential header resolved - ${JSON.stringify(headers.map(([k]) => k))}`);
+        }
+        return headers;
+    };
+}
+/**
+ * The OpenTelemetry `key=value,key2=value2` list, also accepting the `key: value`
+ * form; the FIRST separator splits, so a token containing `=` or `:` survives; a
+ * repeated name keeps its last value.
+ */
+export function parseHeaders(raw) {
+    const out = [];
+    if (raw === undefined || !raw.trim() || raw.trim() === 'null') {
+        return out;
+    }
+    for (const pair of raw.split(',')) {
+        const sep = firstSeparator(pair);
+        if (sep === undefined)
+            continue;
+        const key = pair.slice(0, sep).trim();
+        const value = pair.slice(sep + 1).trim();
+        if (!key)
+            continue;
+        const existing = out.findIndex(([k]) => k === key);
+        if (existing >= 0) {
+            out[existing] = [key, value];
+        }
+        else {
+            out.push([key, value]);
+        }
+    }
+    return out;
+}
+function firstSeparator(pair) {
+    const eq = pair.indexOf('=');
+    const colon = pair.indexOf(':');
+    let sep;
+    if (eq < 0 && colon < 0)
+        return undefined;
+    if (eq < 0)
+        sep = colon;
+    else if (colon < 0)
+        sep = eq;
+    else
+        sep = Math.min(eq, colon);
+    return sep > 0 ? sep : undefined;
+}
+function millis(value, key, fallback) {
+    if (value === undefined)
+        return fallback;
+    const ms = Number.parseInt(value.trim(), 10);
+    if (Number.isFinite(ms) && ms > 0)
+        return ms;
+    log.warn(`${key}=${value} is not a positive number of milliseconds - using ${fallback}`);
+    return fallback;
+}

package/dist/src/otel/export.d.ts

@@ -0,0 +1,44 @@
+import { ForwarderSettings } from './config.js';
+import { Span } from './span.js';
+export declare const INSTRUMENTATION_SCOPE = "mercury-composable-nodejs";
+/** Statuses worth another attempt (the OpenTelemetry SDK's set, plus 408). */
+export declare const RETRYABLE_STATUSES: number[];
+/** The waits between attempts: 5 attempts, 1 s x 1.5^n. */
+export declare const DEFAULT_BACKOFF_MS: number[];
+/** Why an export gave up: the last attempt's diagnostic and the attempt count. */
+export declare class ExportFailure extends Error {
+    readonly attempts: number;
+    readonly detail: string;
+    constructor(attempts: number, detail: string);
+}
+/**
+ * The endpoint must be an http(s) URL with a host - checked at start-up so a
+ * misconfiguration surfaces before the first span.
+ */
+export declare function validateEndpoint(url: string): string;
+/** The OTLP/HTTP exporter for one endpoint. */
+export declare class Exporter {
+    readonly endpoint: string;
+    readonly serviceName: string;
+    readonly scopeVersion: string;
+    readonly compression: string;
+    readonly timeoutMs: number;
+    private readonly headers;
+    private readonly backoffMs;
+    constructor(settings: ForwarderSettings, backoffMs?: number[]);
+    /** The names of the request headers that resolve right now (values are never exposed). */
+    headerNames(): string[];
+    /** The OTLP request body for one span. */
+    encode(span: Span): Uint8Array;
+    /**
+     * Export one span, retrying transient failures on the backoff schedule; throws
+     * `ExportFailure` when the attempts are exhausted or the backend's answer is final.
+     */
+    export(span: Span): Promise<void>;
+    private attempt;
+}
+/**
+ * Render an HTTP rejection so it is actionable from one log line: the status, the
+ * backend's own explanation (bounded), and a hint for the usual causes.
+ */
+export declare function describeHttpFailure(status: number, body: string): string;

package/dist/src/otel/export.js

@@ -0,0 +1,185 @@
+/**
+ * The OTLP/HTTP export: one request per span through the runtime's fetch, with
+ * the engines' retry policy and failure diagnostics (the Rust port's `export.rs`,
+ * the Java `OtelForwarderContext`).
+ *
+ * Retry: telemetry delivery is at-least-once by design - duplicates are tolerated,
+ * drops are what hurt - so a transport failure (connect refused, TLS, a killed
+ * keep-alive, a timeout) and the retryable HTTP statuses (408, 429, 502, 503, 504)
+ * are retried on the OpenTelemetry SDK's default bounded backoff: 5 attempts, 1 s
+ * growing by 1.5x. Any other status fails at once - a 401 will not get better by
+ * waiting.
+ *
+ * Diagnostics: a rejected export is actionable from the forwarder's own warning
+ * line: the status leads, the backend's response body follows (whitespace-collapsed,
+ * bounded), and the rejections that actually happen get a hint. Request headers are
+ * never rendered, so no credential can reach the log.
+ */
+import { getLogger } from '../log.js';
+import { ENDPOINT } from './config.js';
+import { encodeExportRequest, partialSuccess } from './otlp.js';
+import { hex } from './span.js';
+const log = getLogger('mercury.otel');
+export const INSTRUMENTATION_SCOPE = 'mercury-composable-nodejs';
+/** Statuses worth another attempt (the OpenTelemetry SDK's set, plus 408). */
+export const RETRYABLE_STATUSES = [408, 429, 502, 503, 504];
+/** The waits between attempts: 5 attempts, 1 s x 1.5^n. */
+export const DEFAULT_BACKOFF_MS = [1000, 1500, 2250, 3375];
+const CONTENT_TYPE = 'application/x-protobuf';
+const MAX_BODY_CHARS = 256;
+/** Why an export gave up: the last attempt's diagnostic and the attempt count. */
+export class ExportFailure extends Error {
+    attempts;
+    detail;
+    constructor(attempts, detail) {
+        super(attempts > 1 ? `${detail} (after ${attempts} attempts)` : detail);
+        this.attempts = attempts;
+        this.detail = detail;
+        this.name = 'ExportFailure';
+    }
+}
+class AttemptError extends Error {
+    retryable;
+    detail;
+    constructor(retryable, detail) {
+        super(detail);
+        this.retryable = retryable;
+        this.detail = detail;
+    }
+}
+/**
+ * The endpoint must be an http(s) URL with a host - checked at start-up so a
+ * misconfiguration surfaces before the first span.
+ */
+export function validateEndpoint(url) {
+    const trimmed = url.trim();
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (!parsed || !['http:', 'https:'].includes(parsed.protocol) || !parsed.host) {
+        throw new Error(`${ENDPOINT}='${url}' must be an http(s) URL including the signal path, ` +
+            'e.g. http://localhost:4318/v1/traces');
+    }
+    return trimmed;
+}
+/** The OTLP/HTTP exporter for one endpoint. */
+export class Exporter {
+    endpoint;
+    serviceName;
+    scopeVersion;
+    compression;
+    timeoutMs;
+    headers;
+    backoffMs;
+    constructor(settings, backoffMs = DEFAULT_BACKOFF_MS) {
+        this.endpoint = validateEndpoint(settings.endpoint);
+        this.serviceName = settings.serviceName;
+        this.scopeVersion = settings.scopeVersion;
+        this.compression = settings.compression;
+        this.timeoutMs = settings.timeoutMs;
+        this.headers = settings.headers;
+        this.backoffMs = [...backoffMs];
+    }
+    /** The names of the request headers that resolve right now (values are never exposed). */
+    headerNames() {
+        return this.headers().map(([k]) => k);
+    }
+    /** The OTLP request body for one span. */
+    encode(span) {
+        return encodeExportRequest(this.serviceName, INSTRUMENTATION_SCOPE, this.scopeVersion, span);
+    }
+    /**
+     * Export one span, retrying transient failures on the backoff schedule; throws
+     * `ExportFailure` when the attempts are exhausted or the backend's answer is final.
+     */
+    async export(span) {
+        const body = this.encode(span);
+        let attempt = 0;
+        for (;;) {
+            attempt += 1;
+            try {
+                await this.attempt(body);
+                return;
+            }
+            catch (e) {
+                const failure = e;
+                if (failure.retryable && attempt <= this.backoffMs.length) {
+                    log.debug(`OTLP export attempt ${attempt} for span ${hex(span.spanId)} failed ` +
+                        `(${failure.detail}) - retrying`);
+                    await new Promise((resolve) => setTimeout(resolve, this.backoffMs[attempt - 1]).unref());
+                    continue;
+                }
+                throw new ExportFailure(attempt, failure.detail);
+            }
+        }
+    }
+    async attempt(body) {
+        const headers = { 'content-type': CONTENT_TYPE, accept: CONTENT_TYPE };
+        // headers are resolved per export, never baked in: a credential published
+        // after start-up takes effect without a restart
+        for (const [name, value] of this.headers()) {
+            headers[name] = value;
+        }
+        let response;
+        let payload;
+        try {
+            response = await fetch(this.endpoint, {
+                method: 'POST', headers, body: body,
+                signal: AbortSignal.timeout(this.timeoutMs)
+            });
+            payload = new Uint8Array(await response.arrayBuffer());
+        }
+        catch (e) {
+            // the transport failed before an HTTP answer (fetch failed, timeout, TLS) -
+            // retried like the Java exporter retries every IOException
+            const error = e;
+            const detail = error.cause?.message ?? error.message ?? String(e);
+            throw new AttemptError(true, detail);
+        }
+        classify(response.status, payload);
+    }
+}
+function classify(status, payload) {
+    if (status >= 200 && status < 300) {
+        const partial = partialSuccess(payload);
+        if (partial) {
+            log.warn(`OTLP backend accepted the request but rejected ${partial.rejectedSpans} span(s) - ` +
+                partial.errorMessage);
+        }
+        return;
+    }
+    const text = new TextDecoder('utf-8').decode(payload);
+    throw new AttemptError(RETRYABLE_STATUSES.includes(status), describeHttpFailure(status, text));
+}
+/**
+ * Render an HTTP rejection so it is actionable from one log line: the status, the
+ * backend's own explanation (bounded), and a hint for the usual causes.
+ */
+export function describeHttpFailure(status, body) {
+    let text = `HTTP ${status}`;
+    const collapsed = collapse(body);
+    if (collapsed)
+        text += ` - ${collapsed}`;
+    const hint = HINTS[status];
+    if (hint)
+        text += ` | ${hint}`;
+    return text;
+}
+const HINTS = {
+    404: 'check otel.exporter.otlp.endpoint includes the signal path (e.g. .../v1/traces), ' +
+        'not just the vendor base URL',
+    401: 'the backend rejected the credential itself - check otel.exporter.otlp.headers (the ' +
+        'header name and any auth scheme must match what the backend expects)',
+    403: 'the credential was accepted but lacks permission - grant the trace-ingest scope on ' +
+        'the token (the response body above names it)',
+    413: 'the backend rejected the payload as too large',
+    429: 'the backend is rate-limiting; the exporter retries with backoff'
+};
+function collapse(body) {
+    const collapsed = body.split(/\s+/).filter(Boolean).join(' ');
+    return collapsed.length > MAX_BODY_CHARS ? `${collapsed.slice(0, MAX_BODY_CHARS)}...` : collapsed;
+}

package/dist/src/otel/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The OpenTelemetry trace forwarder - the engines' `opentelemetry-forwarder`
+ * extension for this host, opt-in and dependency-free.
+ *
+ * Every traced, non-RPC execution already emits the engines' distributed-trace
+ * dataset on the `distributed.tracing` log stream. With `otel.forwarding=true` the
+ * host ALSO hands each dataset to a function on the engines' extension route
+ * `distributed.trace.forwarder`; the built-in forwarder registered there maps the
+ * dataset to one OpenTelemetry span carrying the host's exact W3C ids and exports
+ * it over OTLP/HTTP (protobuf) to the configured endpoint - Dynatrace, Splunk, an
+ * OpenTelemetry Collector - so one trace spans the engines and the polyglot
+ * functions they call. Off by default: the switch is the only thing that turns it on.
+ */
+import type { AppConfig } from '../config.js';
+import type { FunctionRegistry } from '../registry.js';
+import { Exporter } from './export.js';
+export { DISTRIBUTED_TRACE_FORWARDER } from '../trace.js';
+export { FORWARDING_SWITCH, fixedSettings, parseHeaders, settingsFromConfig } from './config.js';
+export type { ForwarderSettings, HeaderSupplier } from './config.js';
+export { describeHttpFailure, Exporter, ExportFailure, INSTRUMENTATION_SCOPE } from './export.js';
+export { attribute, parseIso8601Nanos, spanFromDataset } from './span.js';
+export type { AttributeValue, Span } from './span.js';
+export { encodeExportRequest, partialSuccess, ProtoReader, ProtoWriter, SPAN_FLAGS_SAMPLED_LOCAL } from './otlp.js';
+/** The engines run the forwarder with two workers. */
+export declare const FORWARDER_INSTANCES = 2;
+/**
+ * The `distributed.trace.forwarder` function bound to one exporter: map the
+ * dataset to a span and export it, logging - never throwing - a failure.
+ */
+export declare function forwarder(exporter: Exporter): (headers: Record<string, string>, body: unknown) => Promise<void>;
+/** Whether `otel.forwarding` is switched on (the text `true`, case-insensitive). */
+export declare function enabled(config: AppConfig): boolean;
+/**
+ * Register the built-in forwarder on `distributed.trace.forwarder` when
+ * `otel.forwarding=true` - the host's start-up hook. Returns the exporter, or
+ * undefined when forwarding is off or a function already occupies the route (an
+ * application's own forwarder wins, as in the engines). A misconfigured endpoint
+ * fails the start.
+ */
+export declare function activate(config: AppConfig, registry: FunctionRegistry): Exporter | undefined;