mercury-composable 4.12.1

package/dist/src/log.js

@@ -0,0 +1,113 @@
+/**
+ * Minimalist logging, presentation-consistent with the Mercury engines.
+ *
+ * Text lines follow the Java reference engine's log4j2 pattern:
+ *
+ *   %d{yyyy-MM-dd HH:mm:ss.SSS} %-5level %logger:%line - %msg
+ *
+ * Level comes from the LOG_LEVEL environment variable when set (mirroring the
+ * engines), else the log.level configuration key, else INFO. log.format
+ * carries the engines' three presentations: text (default), json
+ * (pretty-printed) and compact (the same object on a single line - JSONL -
+ * for log aggregators). Inside a traced request, the JSON presentations add
+ * the application log "context" block (the engines' app-log-context feature -
+ * see log-context.ts).
+ */
+import { appConfig } from './config.js';
+import { logContextConfig } from './log-context.js';
+import { getTrace } from './trace.js';
+const LEVELS = ['DEBUG', 'INFO', 'WARN', 'ERROR'];
+let configured = false;
+let minLevel = 1; // INFO
+let logFormat = 'text';
+function setup() {
+    if (configured)
+        return;
+    const config = appConfig();
+    const levelName = (process.env.LOG_LEVEL ?? String(config.get('log.level', 'INFO'))).toUpperCase();
+    const idx = LEVELS.indexOf(levelName);
+    minLevel = idx === -1 ? 1 : idx;
+    logFormat = String(config.get('log.format', 'text')).toLowerCase();
+    configured = true;
+}
+function timestamp() {
+    const d = new Date();
+    const pad = (n, w = 2) => String(n).padStart(w, '0');
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+        `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}`;
+}
+function callSite() {
+    // frame 0 = Error, 1 = callSite, 2 = Logger method, 3 = the caller
+    const stack = new Error('log call site').stack?.split('\n') ?? [];
+    const frame = stack[4] ?? stack[3] ?? '';
+    // right-to-left parse of ".../name.js:LINE:COL[)]" - linear, no regex scanning
+    const end = frame.endsWith(')') ? frame.length - 1 : frame.length;
+    const colCut = frame.lastIndexOf(':', end - 1);
+    const lineCut = colCut > 0 ? frame.lastIndexOf(':', colCut - 1) : -1;
+    if (lineCut <= 0)
+        return 'unknown:0';
+    const line = frame.slice(lineCut + 1, colCut);
+    if (!/^\d+$/.test(line))
+        return 'unknown:0';
+    const start = Math.max(frame.lastIndexOf('/', lineCut), frame.lastIndexOf('\\', lineCut), frame.lastIndexOf('(', lineCut), frame.lastIndexOf(' ', lineCut)) + 1;
+    const name = frame.slice(start, lineCut).replace(/\.[cm]?js$/, '');
+    return `${name}:${line}`;
+}
+function renderMessage(message, args) {
+    // a structured (object) message stays structural in the JSON presentations
+    // and renders as compact JSON in text mode - used by the distributed-trace
+    // dataset records, which stdout log-ingest agents parse
+    if (typeof message === 'object' && message !== null && !args.length) {
+        return message;
+    }
+    const head = typeof message === 'string' ? message : JSON.stringify(message);
+    return args.length
+        ? `${head} ${args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ')}`
+        : head;
+}
+function write(level, name, message, args) {
+    setup();
+    if (LEVELS.indexOf(level) < minLevel)
+        return;
+    const rendered = renderMessage(message, args);
+    const logger = name ?? callSite();
+    if (logFormat === 'json' || logFormat === 'compact') {
+        const entry = {
+            time: timestamp(),
+            level,
+            logger,
+            message: rendered
+        };
+        // the application log context (the engines' app-log-context feature):
+        // a "context" block on every structured line inside a traced request,
+        // correlating app logs with the distributed-trace telemetry stream
+        const info = getTrace();
+        if (info?.traceId) {
+            const contextConfig = logContextConfig();
+            if (contextConfig.enabled) {
+                entry.context = contextConfig.render(info);
+            }
+        }
+        // engine presentations: json = pretty-printed, compact = one line (JSONL)
+        const indent = logFormat === 'json' ? 2 : undefined;
+        process.stdout.write(JSON.stringify(entry, null, indent) + '\n');
+    }
+    else {
+        const text = typeof rendered === 'string' ? rendered : JSON.stringify(rendered);
+        process.stdout.write(`${timestamp()} ${level.padEnd(5)} ${logger} - ${text}\n`);
+    }
+}
+export class Logger {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+    debug(message, ...args) { write('DEBUG', this.name, message, args); }
+    info(message, ...args) { write('INFO', this.name, message, args); }
+    warn(message, ...args) { write('WARN', this.name, message, args); }
+    error(message, ...args) { write('ERROR', this.name, message, args); }
+}
+/** A logger writing engine-consistent log lines. */
+export function getLogger(name) {
+    return new Logger(name);
+}

package/dist/src/registry.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Function registry and the preload() registration, mirroring the engines'
+ * PreLoad vocabulary: route name, instance count (concurrency limit) and a
+ * private flag. Handlers take (headers, body) — the same two-part input as a
+ * TypedLambdaFunction — and return the reply body (or an EventEnvelope for
+ * full control of status and reply headers).
+ */
+import { EventBus } from './bus.js';
+import type { EventEnvelope } from './envelope.js';
+/**
+ * A function handler returns the reply body, an EventEnvelope for full
+ * control of status and reply headers, or a promise of either - the bus
+ * awaits the result and discriminates with instanceof, so the honest
+ * static type is simply unknown.
+ *
+ * An INTERCEPTOR handler (the engines' EventInterceptor contract) receives
+ * the raw EventEnvelope as its second argument - reply_to and the
+ * correlation id travel the engines' way - replies manually via reply_to,
+ * and its return value is discarded. Streaming producers and relay
+ * functions are interceptors. The runtime discriminates by the service's
+ * interceptor flag, so one structural type covers both flavors.
+ */
+export type Handler = (headers: Record<string, string>, body: unknown) => unknown;
+export interface ServiceDef {
+    route: string;
+    handler: Handler;
+    instances: number;
+    isPrivate: boolean;
+    interceptor: boolean;
+}
+export declare function validateRoute(route: string): string;
+export declare class FunctionRegistry {
+    readonly bus: EventBus;
+    private readonly services;
+    constructor();
+    register(route: string, handler: Handler, options?: {
+        instances?: number;
+        isPrivate?: boolean;
+        interceptor?: boolean;
+    }): ServiceDef;
+    /**
+     * The reply_to mechanism: deliver one envelope to a LOCAL reply sink or
+     * registered function, drop-n-forget (simple routing, never across the
+     * wire - cross-wire replies ride the Event-over-HTTP SSE response).
+     * Returns false when the target no longer exists, so a late segment is a
+     * no-op drop, the engines' semantics.
+     */
+    sendEvent(event: EventEnvelope): boolean;
+    get(route: string): ServiceDef | undefined;
+    exists(route: string): boolean;
+    routes(): ServiceDef[];
+}
+/** the default registry used by preload() and platform.run() */
+export declare const defaultRegistry: FunctionRegistry;
+/**
+ * Register a function handler under a route name (engine PreLoad analog).
+ *
+ *   preload('hello.node', { instances: 10 }, async (headers, body) => ({ ok: true }));
+ */
+export declare function preload(route: string, options: {
+    instances?: number;
+    isPrivate?: boolean;
+    interceptor?: boolean;
+}, handler: Handler): void;

package/dist/src/registry.js

@@ -0,0 +1,80 @@
+/**
+ * Function registry and the preload() registration, mirroring the engines'
+ * PreLoad vocabulary: route name, instance count (concurrency limit) and a
+ * private flag. Handlers take (headers, body) — the same two-part input as a
+ * TypedLambdaFunction — and return the reply body (or an EventEnvelope for
+ * full control of status and reply headers).
+ */
+import { EventBus } from './bus.js';
+const ROUTE_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+export function validateRoute(route) {
+    const trimmed = (route ?? '').trim();
+    if (!ROUTE_PATTERN.test(trimmed) || !trimmed.includes('.')) {
+        throw new Error(`Invalid route name '${trimmed}' - use lowercase letters, digits, ` +
+            'period, hyphen or underscore with at least one period');
+    }
+    return trimmed;
+}
+export class FunctionRegistry {
+    // the registry's own dispatch pipeline (see bus.ts) - shared by the
+    // HTTP host and the local side of PostOffice
+    bus = new EventBus();
+    services = new Map();
+    constructor() {
+        // reply routing for the bus's interceptor error contract
+        this.bus.bindRouter((event) => this.sendEvent(event));
+    }
+    register(route, handler, options = {}) {
+        const validated = validateRoute(route);
+        const service = {
+            route: validated,
+            handler,
+            instances: Math.max(1, Math.trunc(options.instances ?? 10)),
+            isPrivate: options.isPrivate ?? false,
+            interceptor: options.interceptor ?? false
+        };
+        this.services.set(validated, service);
+        return service;
+    }
+    /**
+     * The reply_to mechanism: deliver one envelope to a LOCAL reply sink or
+     * registered function, drop-n-forget (simple routing, never across the
+     * wire - cross-wire replies ride the Event-over-HTTP SSE response).
+     * Returns false when the target no longer exists, so a late segment is a
+     * no-op drop, the engines' semantics.
+     */
+    sendEvent(event) {
+        const route = event.to;
+        if (!route) {
+            return false;
+        }
+        if (this.bus.offerSink(route, event)) {
+            return true;
+        }
+        const service = this.services.get(route);
+        if (!service) {
+            return false;
+        }
+        this.bus.publishEnvelope(service, event);
+        return true;
+    }
+    get(route) {
+        return this.services.get(route);
+    }
+    exists(route) {
+        return this.services.has(route);
+    }
+    routes() {
+        return [...this.services.values()].sort((a, b) => a.route.localeCompare(b.route));
+    }
+}
+/** the default registry used by preload() and platform.run() */
+export const defaultRegistry = new FunctionRegistry();
+/**
+ * Register a function handler under a route name (engine PreLoad analog).
+ *
+ *   preload('hello.node', { instances: 10 }, async (headers, body) => ({ ok: true }));
+ */
+export function preload(route, options, handler) {
+    defaultRegistry.register(route, handler, options);
+}

package/dist/src/server.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The Event API host: POST /api/event, exactly as the engines speak it.
+ *
+ * Mirrors the Java engine's EventApiService: request body = envelope bytes;
+ * x-ttl (ms, floor 1000) bounds handler execution; x-async: true means
+ * drop-n-forget (HTTP 202 with an ack envelope). Transport-level failures
+ * (400 / 403 / 404 / 408) set the HTTP status; a handler's own outcome —
+ * including AppException and unexpected errors — rides HTTP 200 with the
+ * status inside the envelope, exactly like an engine function's reply.
+ * Reserved header hygiene: x-event-api and transported my_* keys are removed
+ * from the handler's header view; the my_cid tag is injected as the
+ * read-only my_correlation_id header.
+ * The host also serves the engines' actuator endpoints (/info, /info/routes,
+ * /env, /health, /livenessprobe) for operations and Kubernetes probes - see
+ * actuator.ts.
+ */
+import * as http from 'node:http';
+import { FunctionRegistry } from './registry.js';
+export declare class EventApiServer {
+    readonly registry: FunctionRegistry;
+    private readonly actuator;
+    /** Thin ingress: protocol guards + header hygiene, then the registry's bus. */
+    constructor(registry?: FunctionRegistry);
+    private handleEvent;
+    /**
+     * Dispatch to an interceptor and classify its first reply exactly like the
+     * engines: unmarked = the classic single-shot response, byte-identical;
+     * marked = the envelope-mode SSE dialect for a caller that accepts
+     * text/event-stream, or the pinned 406 refusal for one that does not.
+     */
+    private dispatchInterceptor;
+    createServer(): http.Server;
+}
+export declare class Platform {
+    readonly registry: FunctionRegistry;
+    constructor(registry?: FunctionRegistry);
+    /** Start the Event API host. Resolves once listening; runs until stopped. */
+    run(options?: {
+        port?: number;
+        host?: string;
+    }): Promise<http.Server>;
+}
+export declare const platform: Platform;

package/dist/src/server.js

@@ -0,0 +1,343 @@
+/**
+ * The Event API host: POST /api/event, exactly as the engines speak it.
+ *
+ * Mirrors the Java engine's EventApiService: request body = envelope bytes;
+ * x-ttl (ms, floor 1000) bounds handler execution; x-async: true means
+ * drop-n-forget (HTTP 202 with an ack envelope). Transport-level failures
+ * (400 / 403 / 404 / 408) set the HTTP status; a handler's own outcome —
+ * including AppException and unexpected errors — rides HTTP 200 with the
+ * status inside the envelope, exactly like an engine function's reply.
+ * Reserved header hygiene: x-event-api and transported my_* keys are removed
+ * from the handler's header view; the my_cid tag is injected as the
+ * read-only my_correlation_id header.
+ * The host also serves the engines' actuator endpoints (/info, /info/routes,
+ * /env, /health, /livenessprobe) for operations and Kubernetes probes - see
+ * actuator.ts.
+ */
+import * as http from 'node:http';
+import { Actuator, sendError } from './actuator.js';
+import { DeliveryTimeout, raceMs } from './bus.js';
+import { appConfig } from './config.js';
+import { EventEnvelope } from './envelope.js';
+import { DATA, dataFrame, envelopeFrame, EOF, errorText, EXCEPTION, exceptionEnvelope, keepAliveMs, STREAM_CALLER_REQUIRED, streamSignal, TEXT_EVENT_STREAM, X_TTL } from './event-stream.js';
+import { CompactFormatError } from './exceptions.js';
+import { getLogger } from './log.js';
+import { defaultRegistry } from './registry.js';
+import { MY_CID_TAG, MY_CORRELATION_ID } from './trace.js';
+const OCTET_STREAM = 'application/octet-stream';
+// the engines' reserved route name for the Event-over-HTTP ingress
+const EVENT_API_SERVICE = 'event.api.service';
+const log = getLogger('mercury.server');
+function transportError(res, status, message) {
+    const reply = new EventEnvelope().setStatus(status).setBody(message);
+    const bytes = reply.toBytes();
+    res.writeHead(status, { 'content-type': OCTET_STREAM, 'content-length': bytes.length });
+    res.end(bytes);
+}
+function handlerHeaders(event) {
+    const headers = {};
+    for (const [k, v] of Object.entries(event.headers)) {
+        const key = k.toLowerCase();
+        if (key !== 'x-event-api' && !key.startsWith('my_')) {
+            headers[k] = v;
+        }
+    }
+    const myCid = event.tags[MY_CID_TAG];
+    if (myCid) {
+        headers[MY_CORRELATION_ID] = myCid;
+    }
+    return headers;
+}
+export class EventApiServer {
+    registry;
+    actuator;
+    /** Thin ingress: protocol guards + header hygiene, then the registry's bus. */
+    constructor(registry = defaultRegistry) {
+        this.registry = registry;
+        this.actuator = new Actuator(registry);
+    }
+    async handleEvent(req, res, raw) {
+        const ttl = Math.max(1000, Number.parseInt(String(req.headers['x-ttl'] ?? '0'), 10) || 0);
+        const isAsync = req.headers['x-async'] === 'true';
+        let event;
+        try {
+            event = EventEnvelope.fromBytes(raw);
+        }
+        catch (e) {
+            if (e instanceof CompactFormatError || e instanceof Error) {
+                transportError(res, 400, e.message);
+                return;
+            }
+            transportError(res, 400, String(e));
+            return;
+        }
+        if (!event.to) {
+            transportError(res, 400, 'Missing routing path');
+            return;
+        }
+        const service = this.registry.get(event.to);
+        if (!service) {
+            transportError(res, 404, `Route ${event.to} not found`);
+            return;
+        }
+        if (service.isPrivate) {
+            transportError(res, 403, `${event.to} is private`);
+            return;
+        }
+        if (!event.sender) {
+            // the engines' EventApiService parity: its PostOffice fills the sender
+            // with its own route when the wire envelope carries none
+            event.setFrom(EVENT_API_SERVICE);
+        }
+        const headers = handlerHeaders(event);
+        const bus = this.registry.bus;
+        const trace = {
+            traceId: event.traceId, tracePath: event.tracePath, cid: event.cid,
+            envelope: event
+        };
+        if (isAsync) {
+            const ack = bus.publish(service, headers, event.body, trace);
+            const bytes = ack.toBytes();
+            res.writeHead(202, { 'content-type': OCTET_STREAM, 'content-length': bytes.length });
+            res.end(bytes);
+            return;
+        }
+        if (service.interceptor) {
+            // interceptor dispatch (the reply_to mechanism): the handler receives
+            // the raw envelope with a per-request reply sink as its reply address
+            // and answers manually - single-shot or streaming
+            const capable = String(req.headers['accept'] ?? '').includes(TEXT_EVENT_STREAM);
+            await this.dispatchInterceptor(res, service, event, headers, ttl, capable);
+            return;
+        }
+        try {
+            const reply = await bus.deliver(service, headers, event.body, ttl, trace);
+            log.info(`Handled ${event.to} status=${reply.getStatus()} ` +
+                `exec_time=${reply.execTime}ms trace_id=${event.traceId ?? 'none'}`);
+            const bytes = reply.toBytes();
+            res.writeHead(200, { 'content-type': OCTET_STREAM, 'content-length': bytes.length });
+            res.end(bytes);
+        }
+        catch (e) {
+            if (e instanceof DeliveryTimeout) {
+                log.warn(`Event ${event.to} timeout for ${ttl} ms (trace_id=${event.traceId ?? 'none'})`);
+                transportError(res, 408, `Timeout for ${ttl} ms`);
+            }
+            else {
+                transportError(res, 500, e.message ?? String(e));
+            }
+        }
+    }
+    /**
+     * Dispatch to an interceptor and classify its first reply exactly like the
+     * engines: unmarked = the classic single-shot response, byte-identical;
+     * marked = the envelope-mode SSE dialect for a caller that accepts
+     * text/event-stream, or the pinned 406 refusal for one that does not.
+     */
+    async dispatchInterceptor(res, service, event, headers, ttl, capable) {
+        const bus = this.registry.bus;
+        const [sinkRoute, queue] = bus.openSink();
+        try {
+            const handlerEvent = new EventEnvelope(event.to, event.body, headers);
+            handlerEvent.setReplyTo(sinkRoute);
+            if (Object.keys(event.tags).length) {
+                // engine-managed tags (e.g. the business correlation-id) ride the
+                // delivered envelope verbatim, the engines' way
+                handlerEvent.tags = { ...event.tags };
+            }
+            if (event.cid) {
+                handlerEvent.setCorrelationId(event.cid);
+            }
+            if (event.traceId) {
+                handlerEvent.setTrace(event.traceId, event.tracePath ?? service.route);
+            }
+            if (event.spanId) {
+                // the caller's span - the handler's span parents onto it
+                handlerEvent.setSpanId(event.spanId);
+            }
+            if (event.sender) {
+                handlerEvent.setFrom(event.sender);
+            }
+            bus.publishEnvelope(service, handlerEvent);
+            const first = await raceMs(queue.next(), Math.max(100, ttl));
+            if (!first) {
+                log.warn(`Event ${event.to} timeout for ${ttl} ms ` +
+                    `(trace_id=${event.traceId ?? 'none'})`);
+                transportError(res, 408, `Timeout for ${ttl} ms`);
+                return;
+            }
+            const marker = streamSignal(first);
+            if (marker === undefined) {
+                // the classic single-shot reply (a manual answer, or the bus's error
+                // contract for an uncaught interceptor exception)
+                log.info(`Handled ${event.to} status=${first.getStatus()} ` +
+                    `exec_time=${first.execTime ?? 0}ms trace_id=${event.traceId ?? 'none'}`);
+                const bytes = first.toBytes();
+                res.writeHead(200, { 'content-type': OCTET_STREAM, 'content-length': bytes.length });
+                res.end(bytes);
+                return;
+            }
+            if (!capable) {
+                // a streaming reply cannot ride a single-shot response
+                transportError(res, 406, STREAM_CALLER_REQUIRED);
+                return;
+            }
+            await streamResponse(res, queue, first, marker, ttl);
+        }
+        finally {
+            bus.closeSink(sinkRoute);
+        }
+    }
+    createServer() {
+        return http.createServer((req, res) => {
+            const url = new URL(req.url ?? '/', 'http://localhost');
+            if (req.method === 'GET') {
+                this.actuator.handle(url.pathname, res).then((handled) => {
+                    if (!handled) {
+                        sendError(res, 404, 'Resource not found');
+                    }
+                }).catch((e) => {
+                    sendError(res, 500, e.message ?? String(e));
+                });
+                return;
+            }
+            if (req.method === 'POST' && url.pathname === '/api/event') {
+                const chunks = [];
+                req.on('data', (chunk) => chunks.push(chunk));
+                req.on('end', () => {
+                    this.handleEvent(req, res, Buffer.concat(chunks)).catch((e) => {
+                        transportError(res, 500, e.message ?? String(e));
+                    });
+                });
+                req.on('error', () => res.destroy());
+                return;
+            }
+            sendError(res, 404, 'Resource not found');
+        });
+    }
+}
+/**
+ * Render the envelope-mode SSE dialect: envelope frames for the head, the
+ * terminals and non-text segments; raw frames for plain text. The x-ttl
+ * allowance (overridable by the producer's head control, in seconds) is the
+ * per-segment idle; expiry fails the stream in-band with the standard 408
+ * error body. Keep-alive comments ride while the producer is quiet
+ * (event.stream.keep.alive, the engines' key).
+ */
+async function streamResponse(res, queue, first, firstMarker, ttl) {
+    let idleMs = ttl;
+    for (const [key, value] of Object.entries(first.headers)) {
+        if (key.toLowerCase() === X_TTL) {
+            const seconds = Number.parseInt(String(value).trim(), 10);
+            if (Number.isFinite(seconds) && seconds > 0) {
+                idleMs = seconds * 1000;
+            }
+        }
+    }
+    res.writeHead(first.getStatus(), {
+        'content-type': TEXT_EVENT_STREAM,
+        'cache-control': 'no-cache'
+    });
+    res.write(envelopeFrame(first));
+    if (firstMarker === DATA) {
+        await streamSegments(res, queue, idleMs);
+    }
+    res.end();
+}
+async function streamSegments(res, queue, idleMs) {
+    const pingMs = keepAliveMs();
+    // a disconnected client ends the stream; late segments are no-op drops
+    for (;;) {
+        if (res.writableEnded || res.destroyed) {
+            log.debug('Client disconnected from event stream');
+            return;
+        }
+        const event = await nextSegment(res, queue, idleMs, pingMs);
+        if (!event) {
+            // idle expiry - fail in-band (the engines' housekeeper parity)
+            const seconds = Math.trunc(idleMs / 1000);
+            res.write(envelopeFrame(exceptionEnvelope(408, `Timeout for ${seconds} seconds`)));
+            return;
+        }
+        const action = classifySegment(event);
+        if (action.warn) {
+            log.warn('Dropping event - invalid x-event-stream signal');
+        }
+        if (action.frame?.length) {
+            res.write(action.frame);
+        }
+        if (action.end) {
+            return;
+        }
+    }
+}
+/**
+ * The wire consequence of one sink envelope in envelope mode: a data frame
+ * (raw or escape-hatch), a terminal envelope frame that ends the response
+ * cleanly (no cosmetic frames on this wire), the in-band terminal for the
+ * bus's uncaught-interceptor-exception contract, or a warned drop.
+ */
+function classifySegment(event) {
+    const marker = streamSignal(event);
+    if (marker === DATA) {
+        return { frame: dataFrame(event, false), end: false };
+    }
+    if (marker === EOF || marker === EXCEPTION) {
+        return { frame: envelopeFrame(event), end: true };
+    }
+    if (marker === undefined && event.hasError()) {
+        // fail in-band with the exact status
+        const frame = envelopeFrame(exceptionEnvelope(event.getStatus(), errorText(event.body)));
+        return { frame, end: true };
+    }
+    return { end: false, warn: true };
+}
+/**
+ * Wait for the next segment within the idle allowance, emitting SSE
+ * keep-alive comments while the producer is quiet (best-effort; pings never
+ * extend the idle allowance).
+ */
+async function nextSegment(res, queue, idleMs, pingMs) {
+    const deadline = Date.now() + idleMs;
+    // ONE pending waiter reused across ping cycles (see raceMs)
+    const pending = queue.next();
+    for (;;) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            return null;
+        }
+        const wait = pingMs > 0 ? Math.min(remaining, pingMs) : remaining;
+        const event = await raceMs(pending, wait);
+        if (event) {
+            return event;
+        }
+        if (Date.now() >= deadline) {
+            return null;
+        }
+        if (!res.writableEnded && !res.destroyed) {
+            res.write(': ping\n\n');
+        }
+    }
+}
+export class Platform {
+    registry;
+    constructor(registry = defaultRegistry) {
+        this.registry = registry;
+    }
+    /** Start the Event API host. Resolves once listening; runs until stopped. */
+    async run(options = {}) {
+        const config = appConfig();
+        const appName = config.getProperty('application.name', 'application');
+        const port = options.port ?? Number(config.get('rest.server.port', 8085));
+        const host = options.host ?? '127.0.0.1';
+        for (const service of this.registry.routes()) {
+            const visibility = service.isPrivate ? 'PRIVATE' : 'PUBLIC';
+            log.info(`Loaded ${visibility} ${service.route}, instances=${service.instances}`);
+        }
+        const server = new EventApiServer(this.registry).createServer();
+        await new Promise((resolve) => server.listen(port, host, resolve));
+        log.info(`${appName} - Event API service started on port ${port}`);
+        return server;
+    }
+}
+export const platform = new Platform();

package/dist/src/trace.d.ts

@@ -0,0 +1,39 @@
+export declare const MY_CID_TAG = "my_cid";
+export declare const MY_CORRELATION_ID = "my_correlation_id";
+export declare const RPC_TAG = "rpc";
+export declare const RESERVED_CONTEXT_TOKENS: Set<string>;
+export interface TraceInfo {
+    route?: string;
+    traceId?: string;
+    tracePath?: string;
+    cid?: string;
+    myCorrelationId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    annotations: Record<string, unknown>;
+    customContext?: Record<string, unknown>;
+}
+/** The trace context of the event being handled, if any. */
+export declare function getTrace(): TraceInfo | undefined;
+/** Attach an annotation to the current trace (returned on the reply envelope). */
+export declare function annotateTrace(key: string, value: unknown): void;
+/**
+ * Add (or remove, when value is null/undefined) a custom key-value in the
+ * application log context - the engines' PostOffice.updateContext twin.
+ *
+ * The key-value is rendered into the "context" block of structured log output
+ * (log.format json/compact) when the app-log-context feature is enabled.
+ * Unlike annotateTrace (which feeds the distributed-trace telemetry), this is
+ * a logging-only sink. No-op outside a hosted request.
+ *
+ * @throws Error if key is one of the reserved context tokens
+ */
+export declare function updateContext(key: string, value: unknown): void;
+/**
+ * Run fn under a trace context - the python trace_context twin. Useful for
+ * callers outside a hosted function (batch jobs, tests) whose PostOffice
+ * calls should carry a trace: the client inherits the context into the
+ * outbound envelope, including the business correlation-id as the
+ * engine-managed my_cid tag.
+ */
+export declare function runWithTrace<T>(info: TraceInfo | undefined, fn: () => T): T;