mercury-composable 4.12.1

package/dist/src/client.js

@@ -0,0 +1,433 @@
+/**
+ * Thin Event-over-HTTP client — the PostOffice analog.
+ *
+ * Sends an event envelope to a peer's /api/event endpoint (a Java or Rust
+ * engine application, or another polyglot function host) with the same HTTP
+ * contract as the engines' relay: content-type application/octet-stream,
+ * accept */*, x-no-stream, x-ttl (ms), x-async for drop-n-forget, optional
+ * security headers, and trace headers (X-Trace-Id plus a W3C traceparent when
+ * the trace id is W3C-shaped).
+ *
+ * The decoded reply envelope is authoritative: an error from the target rides
+ * back as a normal envelope with status >= 400 — inspect reply.getStatus().
+ */
+import { asyncAck, DeliveryTimeout, raceMs } from './bus.js';
+import { EventEnvelope } from './envelope.js';
+import { DATA, ENVELOPE, EOF, errorText, EXCEPTION, exceptionEnvelope, SseParser, STREAM_CALLER_REQUIRED, streamSignal, TEXT_EVENT_STREAM, X_EVENT_NAME, X_EVENT_STREAM } from './event-stream.js';
+import { AppException } from './exceptions.js';
+import { defaultRegistry } from './registry.js';
+import { getTrace, MY_CID_TAG, RPC_TAG } from './trace.js';
+const W3C_TRACE_ID = /^[0-9a-f]{32}$/;
+const W3C_SPAN_ID = /^[0-9a-f]{16}$/;
+export class PostOffice {
+    endpoint;
+    securityHeaders;
+    registry;
+    constructor(endpoint, securityHeaders = {}, registry = defaultRegistry) {
+        this.endpoint = endpoint;
+        this.securityHeaders = securityHeaders;
+        this.registry = registry;
+    }
+    /** In-app delivery through the primitive event bus (private OR public). */
+    async callLocal(route, body, options, isAsync) {
+        const service = this.registry.get(route);
+        if (!service) {
+            return new EventEnvelope().setStatus(404).setBody(`Route ${route} not found`);
+        }
+        const timeoutMs = options.timeoutMs ?? 30000;
+        const event = this.buildEvent(route, body, options);
+        if (!isAsync) {
+            // the engines' RPC round-trip marker: an RPC leg emits no trace
+            // dataset - its metrics fold into the caller's view
+            event.tags[RPC_TAG] ??= String(timeoutMs);
+        }
+        const trace = {
+            traceId: event.traceId, tracePath: event.tracePath, cid: event.cid,
+            envelope: event
+        };
+        const bus = this.registry.bus;
+        if (service.interceptor) {
+            if (isAsync) {
+                bus.publishEnvelope(service, event);
+                return asyncAck();
+            }
+            // RPC to an interceptor: a per-request reply sink is the reply address;
+            // the first envelope classifies exactly like the engines - unmarked =
+            // the reply; marked = a streaming target refusing a single-shot caller
+            const [sinkRoute, queue] = bus.openSink();
+            try {
+                bus.publishEnvelope(service, event.setReplyTo(sinkRoute));
+                const first = await raceMs(queue.next(), Math.max(100, timeoutMs));
+                if (!first) {
+                    return new EventEnvelope().setStatus(408).setBody(`Timeout for ${timeoutMs} ms`);
+                }
+                if (streamSignal(first) !== undefined) {
+                    return new EventEnvelope().setStatus(406).setBody(STREAM_CALLER_REQUIRED);
+                }
+                return first;
+            }
+            finally {
+                bus.closeSink(sinkRoute);
+            }
+        }
+        if (isAsync) {
+            return bus.publish(service, event.headers, event.body, trace);
+        }
+        try {
+            return await bus.deliver(service, event.headers, event.body, timeoutMs, trace);
+        }
+        catch (e) {
+            if (e instanceof DeliveryTimeout) {
+                return new EventEnvelope().setStatus(408).setBody(`Timeout for ${timeoutMs} ms`);
+            }
+            throw e;
+        }
+    }
+    httpHeaders(timeoutMs, isAsync, event) {
+        const headers = {
+            'content-type': 'application/octet-stream',
+            'accept': '*/*',
+            'x-no-stream': 'true',
+            'x-ttl': String(Math.max(100, timeoutMs))
+        };
+        if (isAsync)
+            headers['x-async'] = 'true';
+        for (const [key, value] of Object.entries(this.securityHeaders)) {
+            if (key.toLowerCase() !== 'x-event-format')
+                headers[key] = value;
+        }
+        if (event.traceId) {
+            headers['X-Trace-Id'] = event.traceId;
+            if (W3C_TRACE_ID.test(event.traceId) && event.spanId && W3C_SPAN_ID.test(event.spanId)) {
+                headers['traceparent'] = `00-${event.traceId}-${event.spanId}-01`;
+            }
+        }
+        return headers;
+    }
+    buildEvent(route, body, options) {
+        const event = new EventEnvelope(route, body, options.headers);
+        if (options.fromRoute)
+            event.setFrom(options.fromRoute);
+        const info = getTrace();
+        // fill the sender with the executing function's route (touch parity)
+        if (info?.route && !event.sender) {
+            event.setFrom(info.route);
+        }
+        if (info?.traceId)
+            event.setTrace(info.traceId, info.tracePath ?? route);
+        const cid = options.cid ?? info?.cid;
+        if (cid)
+            event.setCorrelationId(cid);
+        // propagate the business correlation-id to the next touch point as the
+        // engine-managed my_cid tag (the engines' PostOffice.touch parity) - the
+        // receiving host injects it as the read-only my_correlation_id header
+        if (info?.myCorrelationId && !(MY_CID_TAG in event.tags)) {
+            event.tags[MY_CID_TAG] = info.myCorrelationId;
+        }
+        // carry this execution's span so the receiver stores it as its
+        // parent_span_id (touch parity) - also lights up the traceparent header
+        if (info?.spanId) {
+            event.setSpanId(info.spanId);
+        }
+        return event;
+    }
+    async call(route, body, options, isAsync) {
+        const url = options.endpoint ?? this.endpoint;
+        if (!url) {
+            // no endpoint = local: the engines' semantics for an in-app po call
+            return this.callLocal(route, body, options, isAsync);
+        }
+        const timeoutMs = options.timeoutMs ?? 30000;
+        const event = this.buildEvent(route, body, options);
+        if (!isAsync) {
+            // the engines' RPC round-trip marker (see callLocal)
+            event.tags[RPC_TAG] ??= String(timeoutMs);
+        }
+        // +100 ms cushion so the HTTP client does not time out before the target
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: this.httpHeaders(timeoutMs, isAsync, event),
+            body: event.toBytes(),
+            signal: AbortSignal.timeout(Math.max(100, timeoutMs) + 100)
+        });
+        const payload = new Uint8Array(await response.arrayBuffer());
+        try {
+            return EventEnvelope.fromBytes(payload);
+        }
+        catch (e) {
+            throw new AppException(response.status, `Invalid event-over-http response - ${e.message}`);
+        }
+    }
+    /** RPC call: returns the target function's reply envelope. */
+    async request(route, body, options = {}) {
+        return this.call(route, body, options, false);
+    }
+    /** Drop-n-forget: returns the peer's 202 delivery acknowledgement envelope. */
+    async send(route, body, options = {}) {
+        return this.call(route, body, options, true);
+    }
+    /**
+     * Consume a streaming function progressively - the same decoded envelopes
+     * an engine reply route receives: `data` segments, then the `eof` or
+     * `exception` terminal. A non-streaming target yields its one classic reply
+     * (opting in is always safe). `timeoutMs` is the idle allowance between
+     * segments; expiry, a truncated stream and a malformed dialect yield the
+     * in-band exception envelope, then end.
+     *
+     * Remote (an endpoint is given, or set on the constructor): the peer's
+     * /api/event answers the one POST with the envelope-mode SSE dialect.
+     * Local (no endpoint): the same first-envelope classification through a
+     * per-request reply sink on the primitive bus.
+     */
+    async *stream(route, body, options = {}) {
+        const url = options.endpoint ?? this.endpoint;
+        const timeoutMs = options.timeoutMs ?? 30000;
+        const event = this.buildEvent(route, body, options);
+        if (!url) {
+            yield* this.streamLocal(route, event, timeoutMs);
+            return;
+        }
+        yield* this.streamRemote(url, event, timeoutMs);
+    }
+    /**
+     * The relay form of stream() for composition: every decoded envelope
+     * forwards verbatim to the LOCAL replyTo route (typically the caller's own
+     * reply address, handed through by an interceptor), so segments flow
+     * remote peer -> this application -> the original caller with no
+     * buffering. Awaits and returns the last envelope (normally the terminal).
+     */
+    async streamTo(route, body, replyTo, options = {}) {
+        let last = new EventEnvelope().setStatus(500).setBody('Stream produced no events');
+        for await (const segment of this.stream(route, body, options)) {
+            last = segment;
+            const forward = EventEnvelope.fromMap(segment.toMap()).setTo(replyTo);
+            if (!this.registry.sendEvent(forward)) {
+                // the local consumer is gone - late segments are no-op drops
+                break;
+            }
+        }
+        return last;
+    }
+    async *streamLocal(route, event, timeoutMs) {
+        const service = this.registry.get(route);
+        if (!service) {
+            yield new EventEnvelope().setStatus(404).setBody(`Route ${route} not found`);
+            return;
+        }
+        if (!service.interceptor) {
+            // a plain function cannot stream - its single reply is the stream
+            yield await this.callLocal(route, event.body, {
+                headers: event.headers, timeoutMs, fromRoute: event.sender, cid: event.cid
+            }, false);
+            return;
+        }
+        const bus = this.registry.bus;
+        const [sinkRoute, queue] = bus.openSink();
+        try {
+            bus.publishEnvelope(service, event.setReplyTo(sinkRoute));
+            const idleMs = Math.max(100, timeoutMs);
+            let streaming = false;
+            for (;;) {
+                // a lost race terminates the wait, so a fresh next() per cycle is safe
+                const reply = await raceMs(queue.next(), idleMs);
+                if (!reply) {
+                    const seconds = Math.trunc(idleMs / 1000);
+                    yield exceptionEnvelope(408, `Timeout for ${seconds} seconds`);
+                    return;
+                }
+                const [out, done] = classifySinkReply(reply, streaming);
+                streaming = true;
+                yield out;
+                if (done) {
+                    return;
+                }
+            }
+        }
+        finally {
+            bus.closeSink(sinkRoute);
+        }
+    }
+    async *streamRemote(url, event, timeoutMs) {
+        const effectiveCid = event.cid;
+        const headers = this.httpHeaders(timeoutMs, false, event);
+        headers['accept'] = TEXT_EVENT_STREAM;
+        // no total limit - a healthy stream may outlive any fixed total; the
+        // per-read race below is the idle allowance between segments
+        const idleMs = Math.max(1000, timeoutMs);
+        const response = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: event.toBytes()
+        });
+        const contentType = response.headers.get('content-type') ?? '';
+        if (!contentType.startsWith(TEXT_EVENT_STREAM)) {
+            // the peer answered single-shot (a non-streaming target, or an edge
+            // error) - the classic reply, decoded tolerantly
+            const payload = new Uint8Array(await response.arrayBuffer());
+            yield decodeSingleShot(payload, response.status);
+            return;
+        }
+        const body = response.body;
+        if (!body) {
+            yield relayGuard(500, 'Event stream ended without eof', effectiveCid);
+            return;
+        }
+        const reader = body.getReader();
+        try {
+            yield* relayFrames(reader, idleMs, effectiveCid);
+        }
+        catch (e) {
+            yield relayGuard(500, e.message ?? String(e), effectiveCid);
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+        }
+    }
+}
+/**
+ * Pump the envelope-mode SSE frames of one response body: decoded envelopes
+ * out, ending at the terminal (frames after it are discarded); idle expiry
+ * and a transport end without a decoded terminal fail in-band.
+ */
+async function* relayFrames(reader, idleMs, cid) {
+    const parser = new SseParser();
+    let headSeen = false;
+    for (;;) {
+        // a lost race terminates the stream, so a fresh read() per cycle is safe
+        const result = await raceMs(reader.read(), idleMs);
+        if (!result) {
+            const seconds = Math.trunc(idleMs / 1000);
+            yield relayGuard(408, `Timeout for ${seconds} seconds`, cid);
+            return;
+        }
+        if (result.done) {
+            // the dialect ends with a decoded terminal - a bare transport end is a
+            // truncation
+            yield relayGuard(500, 'Event stream ended without eof', cid);
+            return;
+        }
+        for (const [name, text] of parser.feed(result.value)) {
+            const [reply, terminal] = decodeFrame(name, text, headSeen, cid);
+            if (!reply) {
+                continue;
+            }
+            headSeen = true;
+            yield reply;
+            if (terminal) {
+                return; // frames after the terminal are discarded
+            }
+        }
+    }
+}
+/**
+ * Classify one reply-sink envelope exactly like the engines: unmarked before
+ * any segment = the classic single-shot answer; unmarked mid-stream = the
+ * bus's error contract for an uncaught interceptor exception (fails
+ * in-band); marked = a stream segment, terminal on eof/exception.
+ */
+function classifySinkReply(reply, streaming) {
+    const marker = streamSignal(reply);
+    if (marker === undefined) {
+        if (streaming) {
+            return [exceptionEnvelope(reply.getStatus(), errorText(reply.body)), true];
+        }
+        return [reply, true];
+    }
+    return [reply, marker === EOF || marker === EXCEPTION];
+}
+/** An in-band exception envelope synthesized by the consuming relay. */
+function relayGuard(status, message, cid) {
+    const event = exceptionEnvelope(status, message);
+    if (cid) {
+        event.setCorrelationId(cid);
+    }
+    return event;
+}
+/**
+ * Decode one SSE frame of the envelope-mode dialect: an "envelope" frame is
+ * one base64-encoded serialized envelope (the head, the terminals and
+ * non-text segments); any other frame is a raw text segment. Returns
+ * [envelope-or-null, terminal]. Dialect guards fail in-band: the first frame
+ * must be an envelope frame, and a malformed frame ends the stream.
+ */
+function decodeFrame(name, text, headSeen, cid) {
+    if (name === ENVELOPE) {
+        return decodeEnvelopeFrame(text, cid);
+    }
+    if (!headSeen) {
+        // the dialect guarantees an envelope frame first (conformance guard)
+        return [relayGuard(500, 'Invalid event stream - missing envelope head', cid), true];
+    }
+    const segment = new EventEnvelope(undefined, text).setHeader(X_EVENT_STREAM, DATA);
+    if (name) {
+        segment.setHeader(X_EVENT_NAME, name);
+    }
+    if (cid) {
+        segment.setCorrelationId(cid);
+    }
+    return [segment, false];
+}
+/**
+ * One base64-encoded serialized envelope: the head, a terminal, or a
+ * non-text segment - addressing restored to the original caller; a
+ * malformed frame ends the stream in-band.
+ */
+function decodeEnvelopeFrame(text, cid) {
+    let decoded;
+    try {
+        decoded = EventEnvelope.fromBytes(Buffer.from(text, 'base64'));
+    }
+    catch {
+        return [relayGuard(500, 'Invalid event stream - malformed envelope frame', cid), true];
+    }
+    decoded.to = undefined;
+    decoded.replyTo = undefined;
+    if (cid) {
+        decoded.setCorrelationId(cid);
+    }
+    const marker = streamSignal(decoded);
+    return [decoded, marker === EOF || marker === EXCEPTION];
+}
+/**
+ * Decode a single-shot Event-over-HTTP reply: a serialized envelope
+ * normally, with the classic tolerant handling of an edge-level REST error
+ * body ('{"type": "error", "status": n, "message": text}' JSON) and of a
+ * payload that is not a serialized envelope at all.
+ */
+function decodeSingleShot(payload, httpStatus) {
+    if (!payload.length) {
+        return new EventEnvelope().setStatus(httpStatus);
+    }
+    try {
+        const reply = EventEnvelope.fromBytes(payload);
+        reply.replyTo = undefined;
+        return reply;
+    }
+    catch (e) {
+        const restError = restErrorReply(payload, httpStatus);
+        return restError ?? new EventEnvelope().setStatus(400)
+            .setBody(`Invalid event-over-http response - ${e.message}`);
+    }
+}
+/**
+ * An edge-level REST error arrives as JSON, not as a serialized envelope -
+ * unwrap it exactly as the classic relay does; null when it is not one.
+ */
+function restErrorReply(payload, httpStatus) {
+    if (httpStatus < 400) {
+        return null;
+    }
+    try {
+        const data = JSON.parse(Buffer.from(payload).toString('utf-8'));
+        if (data && typeof data === 'object' && !Array.isArray(data)) {
+            const record = data;
+            if (record['type'] === 'error' && typeof record['message'] === 'string') {
+                return new EventEnvelope().setStatus(httpStatus).setBody(record['message']);
+            }
+        }
+    }
+    catch {
+        // not a REST error body
+    }
+    return null;
+}

package/dist/src/config.d.ts

@@ -0,0 +1,27 @@
+export declare const DEFAULT_CANDIDATES: string[];
+/** Extract -Dkey=value runtime overrides (Java/Rust engine syntax). */
+export declare function parseDArgs(argv: string[]): Map<string, unknown>;
+export declare class AppConfig {
+    private store;
+    private readonly overrides;
+    readonly source: string;
+    constructor(path?: string, argv?: string[]);
+    private load;
+    /** Runtime override, checked first on every read (f:setConfig analog). */
+    set(key: string, value: unknown): void;
+    get(key: string, defaultValue?: unknown): unknown;
+    getProperty(key: string, defaultValue?: string): string | undefined;
+    /**
+     * Resolve ${ENV:default} substitution in a text value - the same rules as
+     * configuration values (used by companion config files such as
+     * app-log-context.yaml).
+     */
+    resolveText(value: string): unknown;
+    exists(key: string): boolean;
+    private substitute;
+    private resolveRef;
+}
+/** The shared AppConfig singleton (created on first use). */
+export declare function appConfig(): AppConfig;
+/** Replace the shared AppConfig (used by the CLI before startup). */
+export declare function loadConfig(path?: string): AppConfig;

package/dist/src/config.js

@@ -0,0 +1,161 @@
+/**
+ * Minimalist configuration management, consistent with the Mercury engines.
+ *
+ * Same conventions as the Java/Rust AppConfigReader: configuration lives in
+ * the resources folder (resources/application.yml | .yaml | .properties) with
+ * dotted keys; `-Dkey=value` command-line arguments are runtime parameter
+ * overrides checked first on every read — the same syntax as the Java
+ * engine's JVM system properties and the Rust port's -D arguments (the
+ * f:setConfig analog); `${ENV_VAR:default}` substitution resolves the
+ * environment first, then a base configuration key, then the default.
+ *
+ * Well-known keys shared with the engines: application.name,
+ * rest.server.port (default 8085), log.format (text | json pretty-printed |
+ * compact single-line JSONL), log.level (LOG_LEVEL environment variable
+ * wins).
+ */
+import * as fs from 'node:fs';
+import YAML from 'yaml';
+import { asText } from './envelope.js';
+const REF = /\$\{([^}]+)\}/g;
+const WHOLE_REF = /^\$\{([^}]+)\}$/;
+export const DEFAULT_CANDIDATES = [
+    'resources/application.yml',
+    'resources/application.yaml',
+    'resources/application.properties'
+];
+/** Extract -Dkey=value runtime overrides (Java/Rust engine syntax). */
+export function parseDArgs(argv) {
+    const overrides = new Map();
+    for (const arg of argv) {
+        if (arg.startsWith('-D') && arg.includes('=')) {
+            const idx = arg.indexOf('=');
+            const key = arg.slice(2, idx).trim();
+            if (key)
+                overrides.set(key, arg.slice(idx + 1));
+        }
+    }
+    return overrides;
+}
+function flatten(prefix, node, out) {
+    if (node !== null && typeof node === 'object' && !Array.isArray(node)) {
+        for (const [k, v] of Object.entries(node)) {
+            flatten(prefix ? `${prefix}.${k}` : k, v, out);
+        }
+    }
+    else {
+        out.set(prefix, node);
+    }
+}
+function parseProperties(text) {
+    const result = new Map();
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#') || !line.includes('='))
+            continue;
+        const idx = line.indexOf('=');
+        result.set(line.slice(0, idx).trim(), line.slice(idx + 1).trim());
+    }
+    return result;
+}
+export class AppConfig {
+    store = new Map();
+    overrides;
+    source;
+    constructor(path, argv) {
+        this.overrides = parseDArgs(argv ?? process.argv.slice(2));
+        const candidates = path ? [path] : DEFAULT_CANDIDATES;
+        let loaded = 'none';
+        for (const candidate of candidates) {
+            if (candidate && fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+                this.load(candidate);
+                loaded = candidate;
+                break;
+            }
+        }
+        if (path && loaded === 'none') {
+            throw new Error(`Configuration file not found - ${path}`);
+        }
+        this.source = loaded;
+    }
+    load(path) {
+        const text = fs.readFileSync(path, 'utf-8');
+        if (path.endsWith('.yml') || path.endsWith('.yaml')) {
+            const data = YAML.parse(text) ?? {};
+            const flat = new Map();
+            flatten('', data, flat);
+            this.store = flat;
+        }
+        else {
+            this.store = parseProperties(text);
+        }
+    }
+    /** Runtime override, checked first on every read (f:setConfig analog). */
+    set(key, value) {
+        if (!key?.trim()) {
+            throw new Error('Config key must not be empty');
+        }
+        this.overrides.set(key, value);
+    }
+    get(key, defaultValue = undefined) {
+        if (this.overrides.has(key))
+            return this.overrides.get(key);
+        if (this.store.has(key)) {
+            const value = this.store.get(key);
+            return typeof value === 'string' ? this.substitute(value, defaultValue) : value;
+        }
+        return defaultValue;
+    }
+    getProperty(key, defaultValue) {
+        const value = this.get(key, defaultValue);
+        return value === undefined || value === null ? undefined : asText(value);
+    }
+    /**
+     * Resolve ${ENV:default} substitution in a text value - the same rules as
+     * configuration values (used by companion config files such as
+     * app-log-context.yaml).
+     */
+    resolveText(value) {
+        return this.substitute(value, undefined);
+    }
+    exists(key) {
+        return this.overrides.has(key) || this.store.has(key);
+    }
+    substitute(value, defaultValue) {
+        const whole = WHOLE_REF.exec(value.trim());
+        if (whole) {
+            const resolved = this.resolveRef(whole[1]);
+            return resolved === undefined ? defaultValue : resolved;
+        }
+        return value.replace(REF, (_m, ref) => {
+            const resolved = this.resolveRef(ref);
+            return resolved === undefined || resolved === null ? '' : asText(resolved);
+        });
+    }
+    resolveRef(ref) {
+        const idx = ref.indexOf(':');
+        const name = (idx === -1 ? ref : ref.slice(0, idx)).trim();
+        const fallback = idx === -1 ? undefined : ref.slice(idx + 1);
+        if (name in process.env)
+            return process.env[name];
+        if (this.store.has(name)) {
+            const base = this.store.get(name);
+            if (typeof base === 'string' && /\$\{[^}]+\}/.test(base)) {
+                return this.substitute(base, undefined);
+            }
+            return base;
+        }
+        return fallback;
+    }
+}
+let instance;
+/** The shared AppConfig singleton (created on first use). */
+export function appConfig() {
+    instance ??= new AppConfig();
+    return instance;
+}
+/** Replace the shared AppConfig (used by the CLI before startup). */
+export function loadConfig(path) {
+    instance = new AppConfig(path);
+    return instance;
+}

package/dist/src/default-log-context.yaml

@@ -0,0 +1,19 @@
+#
+# Built-in default application log context (the engines' default-log-context.yaml twin).
+#
+# The log-context feature is ON by default using this template. It applies to the
+# structured JSON presentations (log.format=json or compact).
+#
+# To customize the context block, provide your own app-log-context.yaml in the
+# application's resources folder (next to application.yml) - it replaces this
+# default entirely.
+# To turn the feature off, set app.log.context=false in the configuration.
+#
+context:
+  cid: $cid
+  traceId: $traceId
+  tracePath: $tracePath
+  spanId: $spanId
+  parentSpanId: $parentSpanId
+  service: $service
+  timestamp: $utc

package/dist/src/envelope.d.ts

@@ -0,0 +1,44 @@
+/** ISO-8601 UTC with millisecond precision, e.g. 2026-07-21T12:00:00.000Z */
+export declare function isoUtc(date?: Date): string;
+/** Render a scalar as text: primitives via String, structures via JSON. */
+export declare function asText(value: unknown): string;
+export declare class EventEnvelope {
+    id: string;
+    to?: string;
+    sender?: string;
+    replyTo?: string;
+    cid?: string;
+    traceId?: string;
+    tracePath?: string;
+    spanId?: string;
+    status?: number;
+    headers: Record<string, string>;
+    body: unknown;
+    execTime?: number;
+    roundTrip?: number;
+    tags: Record<string, string>;
+    annotations: Record<string, unknown>;
+    stack?: string;
+    objType?: string;
+    exception?: Uint8Array;
+    constructor(to?: string, body?: unknown, headers?: Record<string, string>);
+    setTo(route: string): this;
+    setFrom(route: string): this;
+    setHeader(key: string, value: unknown): this;
+    setBody(body: unknown): this;
+    setStatus(status: number): this;
+    setCorrelationId(cid: string): this;
+    setTrace(traceId: string, tracePath: string): this;
+    setSpanId(spanId: string): this;
+    setReplyTo(route?: string): this;
+    getStatus(): number;
+    hasError(): boolean;
+    toMap(): Record<string, unknown>;
+    toBytes(): Uint8Array<ArrayBuffer>;
+    /** The optional wire fields that arrive as strings (wire key -> assignment). */
+    private static copyStringFields;
+    /** The optional numeric fields (absent and nil are equivalent on the wire). */
+    private static copyNumericFields;
+    static fromMap(data: Record<string, unknown>): EventEnvelope;
+    static fromBytes(data: Uint8Array): EventEnvelope;
+}