mercury-composable 4.12.1

package/dist/src/event-stream.js

@@ -0,0 +1,359 @@
+/**
+ * Event streaming: the multi-shot reply contract and the envelope-mode SSE dialect.
+ *
+ * The platform's native streaming pattern (all four runtimes): the caller provides
+ * a reply address; the callee streams events to it until a terminal signal. Each
+ * segment is one event to the caller's reply_to, marked with the reserved envelope
+ * header `x-event-stream: data | eof | exception`. On the Event-over-HTTP wire, the
+ * peer answers the one POST with a Server-Sent Events response in a hybrid dialect:
+ * envelope frames (the reserved SSE event name "envelope", one base64-encoded
+ * serialized envelope per frame) wherever envelope semantics matter - the head, the
+ * terminals and non-text segments - and raw SSE frames for plain text segments, so
+ * token relays stay near-zero overhead.
+ *
+ * EventStreamWriter is the producer helper - the engines' exact API:
+ *
+ *   const out = EventStreamWriter.fromRequest(event);  // an interceptor's envelope
+ *   out.first(200, 'text/event-stream');
+ *   out.write('hello');                                // data segment
+ *   out.writeNamed('tokens', { n: 2 });                // named (typed) SSE event
+ *   out.close({ usage });                              // end of transmission
+ *   // or out.fail(e);                                 // in-band failure
+ *
+ * Writes after close/fail are dropped (debug log), mirroring the engines. An
+ * in-band failure body carries the standard error key-values
+ * '{"type": "error", "status": n, "message": text}'.
+ */
+import { appConfig } from './config.js';
+import { EventEnvelope } from './envelope.js';
+import { AppException } from './exceptions.js';
+import { getLogger } from './log.js';
+import { getTrace } from './trace.js';
+import { defaultRegistry } from './registry.js';
+/** reserved envelope header (internal protocol, never on the HTTP wire) */
+export const X_EVENT_STREAM = 'x-event-stream';
+/** optional companion on a data event: maps to the SSE "event:" field */
+export const X_EVENT_NAME = 'x-event-name';
+/** marker vocabulary - deliberately the engines' ObjectStream vocabulary */
+export const DATA = 'data';
+export const EOF = 'eof';
+export const EXCEPTION = 'exception';
+/**
+ * reserved SSE event name of the envelope-mode wire dialect: a frame with
+ * this name carries one base64-encoded serialized EventEnvelope
+ */
+export const ENVELOPE = 'envelope';
+export const X_TTL = 'x-ttl';
+export const TEXT_EVENT_STREAM = 'text/event-stream';
+export const STREAM_CALLER_REQUIRED = 'Streaming function requires a caller that accepts text/event-stream';
+/** reserved envelope headers a raw SSE frame may carry without loss */
+const RESERVED_HEADERS = new Set([X_EVENT_STREAM, X_EVENT_NAME, X_TTL]);
+const log = getLogger('mercury.stream');
+/** The x-event-stream marker (lowercased), or undefined for an unmarked envelope. */
+export function streamSignal(event) {
+    for (const [key, value] of Object.entries(event.headers)) {
+        if (key.toLowerCase() === X_EVENT_STREAM) {
+            return value.toLowerCase();
+        }
+    }
+    return undefined;
+}
+/** The x-event-name companion header (the SSE "event:" field), if any. */
+export function streamEventName(event) {
+    for (const [key, value] of Object.entries(event.headers)) {
+        if (key.toLowerCase() === X_EVENT_NAME) {
+            return value;
+        }
+    }
+    return undefined;
+}
+/** The message text of an unmarked error reply (objects render as JSON). */
+export function errorText(body) {
+    if (body === undefined || body === null) {
+        return 'Stream failed';
+    }
+    return typeof body === 'string' ? body : JSON.stringify(body);
+}
+/** The standard error key-values: '{"type": "error", "status": n, "message": text}' */
+export function errorBody(status, message) {
+    return { type: 'error', status, message };
+}
+/** An in-band exception envelope with the standard error body. */
+export function exceptionEnvelope(status, message) {
+    return new EventEnvelope()
+        .setHeader(X_EVENT_STREAM, EXCEPTION)
+        .setStatus(status)
+        .setBody(errorBody(status, message));
+}
+/** One SSE frame: optional "event:" line, one "data:" line per text line. */
+export function sseFrame(eventName, text) {
+    const lines = [];
+    if (eventName) {
+        lines.push(`event: ${eventName}\n`);
+    }
+    for (const line of text.split('\n')) {
+        lines.push(`data: ${line}\n`);
+    }
+    lines.push('\n');
+    return Buffer.from(lines.join(''), 'utf-8');
+}
+/**
+ * One envelope-mode wire frame: the envelope serialized verbatim - with the
+ * host-internal addressing cleared, because the consuming relay rewrites
+ * addressing to the original caller - as base64 under the reserved name.
+ */
+export function envelopeFrame(event) {
+    const clone = EventEnvelope.fromMap(event.toMap());
+    clone.to = undefined;
+    clone.replyTo = undefined;
+    const encoded = Buffer.from(clone.toBytes()).toString('base64');
+    return sseFrame(ENVELOPE, encoded);
+}
+/**
+ * A data segment may ride a raw SSE frame only when the frame carries it
+ * losslessly: a 200 status, no custom envelope headers, a user event name
+ * clear of the reserved word, and a text (or empty) body without a carriage
+ * return - SSE normalizes line endings. Everything else takes the
+ * envelope-frame escape hatch.
+ */
+export function rawStreamable(event) {
+    if (event.getStatus() !== 200) {
+        return false;
+    }
+    for (const [key, value] of Object.entries(event.headers)) {
+        const lowered = key.toLowerCase();
+        if (!RESERVED_HEADERS.has(lowered)) {
+            return false;
+        }
+        if (lowered === X_EVENT_NAME && value === ENVELOPE) {
+            return false;
+        }
+    }
+    const body = event.body;
+    return body === undefined || body === null ||
+        (typeof body === 'string' && !body.includes('\r'));
+}
+/**
+ * One envelope-mode data frame: the first event always rides an envelope
+ * frame (it carries the head control); a losslessly raw-able text segment
+ * rides a raw frame; a bare no-op segment carries nothing.
+ */
+export function dataFrame(event, firstFrame) {
+    if (firstFrame || !rawStreamable(event)) {
+        return envelopeFrame(event);
+    }
+    if (event.body === undefined || event.body === null) {
+        return Buffer.alloc(0);
+    }
+    return sseFrame(streamEventName(event), event.body);
+}
+/**
+ * SSE keep-alive comment interval in ms (`event.stream.keep.alive`,
+ * default 30s; 0 disables - the engines' config key).
+ */
+export function keepAliveMs() {
+    const raw = String(appConfig().getProperty('event.stream.keep.alive', '30s') ?? '30s')
+        .trim().toLowerCase();
+    if (raw === '0' || raw === '0s' || raw === '0ms' || raw === '0m') {
+        return 0;
+    }
+    const parse = (text) => Number.parseInt(text, 10);
+    let value;
+    if (raw.endsWith('ms')) {
+        value = parse(raw.slice(0, -2));
+    }
+    else if (raw.endsWith('s')) {
+        value = parse(raw.slice(0, -1)) * 1000;
+    }
+    else if (raw.endsWith('m')) {
+        value = parse(raw.slice(0, -1)) * 60_000;
+    }
+    else {
+        value = parse(raw) * 1000;
+    }
+    return Number.isFinite(value) ? value : 30_000;
+}
+/**
+ * Incremental SSE frame parser: byte-level line split (a newline is a single
+ * byte, so this is UTF-8 safe), one-leading-space value strip, comment/id/
+ * retry suppression, multi-line data joined per the SSE specification.
+ * Mirrors the engines' parsers.
+ */
+export class SseParser {
+    pending = Buffer.alloc(0);
+    dataLines = [];
+    eventName;
+    /** Feed one body chunk; return the completed [event_name, data] events. */
+    feed(chunk) {
+        const buffer = Buffer.concat([this.pending, Buffer.from(chunk)]);
+        const events = [];
+        let start = 0;
+        for (let i = 0; i < buffer.length; i++) {
+            if (buffer[i] !== 0x0a) { // '\n'
+                continue;
+            }
+            const end = i > start && buffer[i - 1] === 0x0d ? i - 1 : i;
+            this.onLine(buffer.subarray(start, end).toString('utf-8'), events);
+            start = i + 1;
+        }
+        this.pending = Buffer.from(buffer.subarray(start));
+        return events;
+    }
+    /**
+     * One SSE line: a blank line dispatches the pending event; a comment line
+     * (leading colon) is consumed, never forwarded; id, retry and unknown
+     * fields are ignored (SSE specification).
+     */
+    onLine(line, events) {
+        if (!line) {
+            if (this.dataLines.length) {
+                events.push([this.eventName, this.dataLines.join('\n')]);
+            }
+            this.dataLines = [];
+            this.eventName = undefined;
+            return;
+        }
+        if (line.startsWith(':')) {
+            return;
+        }
+        const colon = line.indexOf(':');
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' ')) {
+            value = value.slice(1);
+        }
+        if (field === 'data') {
+            this.dataLines.push(value);
+        }
+        else if (field === 'event') {
+            this.eventName = value;
+        }
+    }
+}
+/**
+ * Producer helper for a multi-shot reply - the engines' exact API.
+ *
+ * Only an interceptor function can stream: it receives the raw envelope, so
+ * the caller-provided reply address travels the engines' way
+ * (EventStreamWriter.fromRequest(event) reads reply_to and the correlation
+ * id). Segments route to the LOCAL reply address through the primitive event
+ * bus - simple routing to a local function or reply sink, never across the
+ * wire (cross-wire replies ride the Event-over-HTTP SSE response, exactly as
+ * on the engines).
+ */
+export class EventStreamWriter {
+    registry;
+    replyTo;
+    cid;
+    firstStatus = 200;
+    firstContentType;
+    firstTtlSeconds = 0;
+    headSent = false;
+    isClosed = false;
+    constructor(replyTo, correlationId, registry = defaultRegistry) {
+        if (!replyTo) {
+            throw new AppException(400, 'Streaming producer requires a reply_to address');
+        }
+        this.registry = registry;
+        this.replyTo = replyTo;
+        this.cid = correlationId;
+    }
+    /**
+     * Create a writer from the incoming request envelope (the usual form for
+     * an interceptor function).
+     */
+    static fromRequest(event, registry = defaultRegistry) {
+        return new EventStreamWriter(event.replyTo, event.cid, registry);
+    }
+    /**
+     * Optional head control carried by the first outgoing event: response
+     * status, content type, and an optional idle-allowance override in seconds
+     * between segments.
+     */
+    first(status, contentType, ttlSeconds) {
+        this.firstStatus = Math.trunc(status);
+        this.firstContentType = contentType;
+        if (ttlSeconds !== undefined) {
+            this.firstTtlSeconds = Math.trunc(ttlSeconds);
+        }
+        return this;
+    }
+    /** Send one `data` segment (text, bytes, object, array - any payload). */
+    write(segment) {
+        this.send(DATA, segment, undefined);
+    }
+    /** Send one named segment - the name maps to the SSE "event:" field. */
+    writeNamed(eventName, segment) {
+        this.send(DATA, segment, eventName);
+    }
+    /** Declare end of transmission, with optional trailing metadata. */
+    close(trailingMetadata) {
+        if (this.isClosed) {
+            return;
+        }
+        this.isClosed = true;
+        this.emit(this.envelope(EOF, trailingMetadata, undefined));
+    }
+    /** Declare an in-band failure and end the stream. */
+    fail(error) {
+        if (this.isClosed) {
+            return;
+        }
+        this.isClosed = true;
+        let status = error instanceof AppException ? error.status : 500;
+        status = status >= 400 ? status : 500;
+        const message = error.message || error.name;
+        const event = this.envelope(EXCEPTION, errorBody(status, message), undefined);
+        event.setStatus(status);
+        this.emit(event);
+    }
+    /** True when the stream has been closed or failed. */
+    get closed() {
+        return this.isClosed;
+    }
+    send(marker, body, eventName) {
+        if (this.isClosed) {
+            log.debug(`Segment to ${this.replyTo} dropped - stream already closed`);
+            return;
+        }
+        this.emit(this.envelope(marker, body, eventName));
+    }
+    envelope(marker, body, eventName) {
+        const event = new EventEnvelope(this.replyTo, body).setHeader(X_EVENT_STREAM, marker);
+        if (this.cid) {
+            event.setCorrelationId(this.cid);
+        }
+        if (eventName) {
+            event.setHeader(X_EVENT_NAME, eventName);
+        }
+        if (!this.headSent) {
+            this.headSent = true;
+            event.setStatus(this.firstStatus);
+            if (this.firstContentType) {
+                event.setHeader('content-type', this.firstContentType);
+            }
+            if (this.firstTtlSeconds > 0) {
+                event.setHeader(X_TTL, String(this.firstTtlSeconds));
+            }
+        }
+        // segments inherit the producer's identity, trace and span, so a
+        // consuming engine's per-segment delivery spans parent onto this
+        // function (the engines' po.send/touch parity)
+        const info = getTrace();
+        if (info?.route) {
+            event.setFrom(info.route);
+        }
+        if (info?.traceId) {
+            event.setTrace(info.traceId, info.tracePath ?? this.replyTo);
+            if (info.spanId) {
+                event.setSpanId(info.spanId);
+            }
+        }
+        return event;
+    }
+    emit(event) {
+        if (!this.registry.sendEvent(event)) {
+            log.warn(`Event dropped - route ${this.replyTo} not found`);
+        }
+    }
+}

package/dist/src/exceptions.d.ts

@@ -0,0 +1,18 @@
+/**
+ * AppException mirrors the Java/Rust engines' AppException: an intentional
+ * application error carrying an HTTP-style status code and a message. Thrown
+ * from a function handler, it becomes the portable error contract on the
+ * wire: envelope status (>= 400) + body (the error message).
+ */
+export declare class AppException extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * The payload used the classic compact wire format (single-character map
+ * keys). This implementation speaks the language-neutral standard format
+ * only; engines default to standard for Event over HTTP.
+ */
+export declare class CompactFormatError extends Error {
+    constructor(message: string);
+}

package/dist/src/exceptions.js

@@ -0,0 +1,25 @@
+/**
+ * AppException mirrors the Java/Rust engines' AppException: an intentional
+ * application error carrying an HTTP-style status code and a message. Thrown
+ * from a function handler, it becomes the portable error contract on the
+ * wire: envelope status (>= 400) + body (the error message).
+ */
+export class AppException extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'AppException';
+        this.status = Math.trunc(status);
+    }
+}
+/**
+ * The payload used the classic compact wire format (single-character map
+ * keys). This implementation speaks the language-neutral standard format
+ * only; engines default to standard for Event over HTTP.
+ */
+export class CompactFormatError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CompactFormatError';
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Mercury Composable — polyglot functions for Node.js.
+ *
+ * A lightweight Event-over-HTTP function host and client: write decoupled
+ * functions in JavaScript/TypeScript and let Java/Rust Mercury engines
+ * orchestrate them from Event Script flows and MiniGraph knowledge graphs
+ * through the declarative yaml.event.over.http routing map. Orchestration
+ * stays in the engines; this package deliberately provides functions only,
+ * plus the minimalist utilities (configuration, logging, telemetry) shared
+ * with the engine style.
+ */
+export { PostOffice } from './client.js';
+export type { CallOptions } from './client.js';
+export { AppConfig, appConfig, loadConfig } from './config.js';
+export { EventEnvelope, isoUtc } from './envelope.js';
+export { DATA, ENVELOPE, EOF, EventStreamWriter, EXCEPTION, SseParser, streamEventName, streamSignal, X_EVENT_NAME, X_EVENT_STREAM } from './event-stream.js';
+export { AppException, CompactFormatError } from './exceptions.js';
+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 type { TraceInfo } from './trace.js';
+export { VERSION } from './version.js';

package/dist/src/index.js

@@ -0,0 +1,21 @@
+/**
+ * Mercury Composable — polyglot functions for Node.js.
+ *
+ * A lightweight Event-over-HTTP function host and client: write decoupled
+ * functions in JavaScript/TypeScript and let Java/Rust Mercury engines
+ * orchestrate them from Event Script flows and MiniGraph knowledge graphs
+ * through the declarative yaml.event.over.http routing map. Orchestration
+ * stays in the engines; this package deliberately provides functions only,
+ * plus the minimalist utilities (configuration, logging, telemetry) shared
+ * with the engine style.
+ */
+export { PostOffice } from './client.js';
+export { AppConfig, appConfig, loadConfig } from './config.js';
+export { EventEnvelope, isoUtc } from './envelope.js';
+export { DATA, ENVELOPE, EOF, EventStreamWriter, EXCEPTION, SseParser, streamEventName, streamSignal, X_EVENT_NAME, X_EVENT_STREAM } from './event-stream.js';
+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 { VERSION } from './version.js';

package/dist/src/log-context.d.ts

@@ -0,0 +1,24 @@
+import { TraceInfo } from './trace.js';
+/** Parsed context template: output key -> reserved token or constant. */
+export declare class LogContextConfig {
+    readonly enabled: boolean;
+    private readonly tokens;
+    private readonly constants;
+    constructor(template: Record<string, unknown> | undefined);
+    /**
+     * One template entry: a reserved $token, or a constant (env-resolved value
+     * or literal; an unset ${VAR} with no default resolves to undefined and is
+     * dropped) - the engines' parseEntry.
+     */
+    private parseEntry;
+    /**
+     * The context block for one log line: template tokens resolved live,
+     * constants, and the developer's custom key-values. Keys resolving to
+     * null/undefined are omitted.
+     */
+    render(info: TraceInfo): Record<string, unknown>;
+}
+/** The shared context template (loaded on first structured log line). */
+export declare function logContextConfig(): LogContextConfig;
+/** Test seam: reset so the next structured log line reloads the template. */
+export declare function resetLogContextForTest(): void;

package/dist/src/log-context.js

@@ -0,0 +1,172 @@
+/**
+ * Application log context - the engines' app-log-context feature.
+ *
+ * When enabled (`app.log.context`, default true), the structured log
+ * presentations (log.format json/compact) add a `context` block to every log
+ * line written inside a traced request, so application logs and the
+ * distributed-trace telemetry stream correlate end to end in one aggregation.
+ *
+ * The context template mirrors the engines' contract exactly:
+ * - The built-in default template carries the standard trace context
+ *   (cid, traceId, tracePath, spanId, parentSpanId, service, timestamp).
+ * - An application may replace it entirely with its own app-log-context.yaml
+ *   in the resources folder (next to application.yml), mapping each output
+ *   key to a reserved `$token` - resolved live per log line - or a constant
+ *   (a literal, or `${ENV:default}` resolved once at load).
+ * - `app.log.context=false` opts out.
+ * - The `cid` token is the BUSINESS correlation-id only (the engine-managed
+ *   my_cid tag); an internal routing id under the `cid` label would mislead
+ *   log aggregation.
+ * - Developer-supplied key-values (updateContext) merge into the block; keys
+ *   resolving to null are omitted, never "null".
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'yaml';
+import { appConfig } from './config.js';
+import { isoUtc } from './envelope.js';
+import { getLogger } from './log.js';
+import { RESERVED_CONTEXT_TOKENS } from './trace.js';
+const FEATURE_FLAG = 'app.log.context';
+const CONFIG_FILE = 'app-log-context.yaml';
+// the built-in default template ships as a packaged resource next to this
+// module, exactly like the engines' classpath:/default-log-context.yaml
+const DEFAULT_FILE = 'default-log-context.yaml';
+/** The template's `context:` section, or undefined when absent/malformed. */
+function contextSection(data) {
+    const section = data && typeof data === 'object'
+        ? data.context : undefined;
+    if (typeof section === 'object' && section !== null && !Array.isArray(section)) {
+        return section;
+    }
+    return undefined;
+}
+/** The built-in default template from the packaged default-log-context.yaml. */
+function defaultTemplate() {
+    const candidate = join(dirname(fileURLToPath(import.meta.url)), DEFAULT_FILE);
+    if (!existsSync(candidate)) {
+        return undefined;
+    }
+    return contextSection(parse(readFileSync(candidate, 'utf-8')) ?? {});
+}
+/** Resolve a reserved token to its live value (undefined when absent). */
+function tokenValue(info, token) {
+    switch (token) {
+        case 'cid': return info.myCorrelationId;
+        case 'traceId': return info.traceId;
+        case 'tracePath': return info.tracePath;
+        case 'spanId': return info.spanId;
+        case 'parentSpanId': return info.parentSpanId;
+        case 'service': return info.route;
+        case 'utc': return isoUtc();
+        default: return undefined;
+    }
+}
+/** Parsed context template: output key -> reserved token or constant. */
+export class LogContextConfig {
+    enabled;
+    tokens = {};
+    constants = {};
+    constructor(template) {
+        for (const [outputKey, raw] of Object.entries(template ?? {})) {
+            this.parseEntry(outputKey, typeof raw === 'string' ? raw : String(raw));
+        }
+        this.enabled = Object.keys(this.tokens).length > 0
+            || Object.keys(this.constants).length > 0;
+    }
+    /**
+     * One template entry: a reserved $token, or a constant (env-resolved value
+     * or literal; an unset ${VAR} with no default resolves to undefined and is
+     * dropped) - the engines' parseEntry.
+     */
+    parseEntry(outputKey, value) {
+        if (value.startsWith('$') && !value.startsWith('${')) {
+            const token = value.slice(1);
+            if (!RESERVED_CONTEXT_TOKENS.has(token)) {
+                throw new Error(`Invalid log context token '${value}' for key ` +
+                    `'${outputKey}' - allowed tokens: ` +
+                    [...RESERVED_CONTEXT_TOKENS].sort((a, b) => a.localeCompare(b)).join(', '));
+            }
+            this.tokens[outputKey] = token;
+            return;
+        }
+        const resolved = appConfig().resolveText(value);
+        if (resolved !== undefined && resolved !== null) {
+            this.constants[outputKey] = resolved;
+        }
+    }
+    /**
+     * The context block for one log line: template tokens resolved live,
+     * constants, and the developer's custom key-values. Keys resolving to
+     * null/undefined are omitted.
+     */
+    render(info) {
+        const out = {};
+        for (const [outputKey, token] of Object.entries(this.tokens)) {
+            const value = tokenValue(info, token);
+            if (value !== undefined && value !== null) {
+                out[outputKey] = value;
+            }
+        }
+        Object.assign(out, this.constants);
+        for (const [key, value] of Object.entries(info.customContext ?? {})) {
+            if (value !== undefined && value !== null) {
+                out[key] = value;
+            }
+        }
+        return out;
+    }
+}
+/**
+ * Resolve the active template; never logs itself - the caller emits the
+ * warning AFTER installing the config, so the log line (which renders through
+ * this feature) cannot re-enter.
+ */
+function load() {
+    const config = appConfig();
+    if ((config.getProperty(FEATURE_FLAG, 'true') ?? 'true').toLowerCase() === 'false') {
+        return { config: new LogContextConfig(undefined) };
+    }
+    // an application override replaces the default entirely - same resources
+    // convention as application.yml
+    const source = config.source;
+    const folder = source !== 'none' ? dirname(source) : 'resources';
+    const candidate = join(folder || 'resources', CONFIG_FILE);
+    if (existsSync(candidate)) {
+        const section = contextSection(parse(readFileSync(candidate, 'utf-8')) ?? {});
+        if (!section) {
+            // the engines log a warning and disable; mirror the outcome
+            return {
+                config: new LogContextConfig(undefined),
+                warning: `Log context config has no 'context' section - feature disabled (${candidate})`
+            };
+        }
+        return { config: new LogContextConfig(section) };
+    }
+    const template = defaultTemplate();
+    if (!template) {
+        return {
+            config: new LogContextConfig(undefined),
+            warning: `Built-in ${DEFAULT_FILE} missing - log context feature disabled`
+        };
+    }
+    return { config: new LogContextConfig(template) };
+}
+let instance;
+/** The shared context template (loaded on first structured log line). */
+export function logContextConfig() {
+    if (!instance) {
+        const { config, warning } = load();
+        instance = config;
+        if (warning) {
+            // safe: the instance is installed first, so this line cannot re-enter
+            getLogger('mercury.log').warn(warning);
+        }
+    }
+    return instance;
+}
+/** Test seam: reset so the next structured log line reloads the template. */
+export function resetLogContextForTest() {
+    instance = undefined;
+}

package/dist/src/log.d.ts

@@ -0,0 +1,14 @@
+declare const LEVELS: readonly ["DEBUG", "INFO", "WARN", "ERROR"];
+export type Level = (typeof LEVELS)[number];
+type LogMessage = string | Record<string, unknown>;
+export declare class Logger {
+    private readonly name?;
+    constructor(name?: string | undefined);
+    debug(message: LogMessage, ...args: unknown[]): void;
+    info(message: LogMessage, ...args: unknown[]): void;
+    warn(message: LogMessage, ...args: unknown[]): void;
+    error(message: LogMessage, ...args: unknown[]): void;
+}
+/** A logger writing engine-consistent log lines. */
+export declare function getLogger(name?: string): Logger;
+export {};