@adriangalilea/utils 7.1.0 → 9.0.0

package/dist/universal/log.js

@@ -1,108 +1,213 @@
 /**
- * Terminal-first logger with two renderings and one automatic decision.
+ * The logger: one stream of events, written the same way by go-utils,
+ * ts-utils and py-utils. The contract is the utils README
+ * (github.com/adriangalilea/utils); this file is the TypeScript side of it.
  *
- * Two knobs, never confusing: format = how lines render, time = whether
- * lines carry time. Each defaults sensibly and independently.
+ * Writing
+ *     Every verb takes a message, then optional fields:
+ *         log.warn("retrying", { attempt: 2 })
+ *         log.error("charge failed", { err })
+ *     The message says what happened, the fields say with what. Fields are a
+ *     plain object; anything else panics.
  *
- * Format — LOG_FORMAT=human|record, or setLogFormat(). Default by TTY
- *     detection on the sink: a TTY gets human (symbols, color, a line meant
- *     for eyes), anything else gets record (level words, plain text, a line
- *     meant for a file read later). Detection happens on the stream actually
- *     written to (stderr), never a sibling stream.
+ * Verbs print at fixed levels
+ *     error ⨯ · fail ⨯ (error) · warn ⚠ · warnOnce ⚠ (warn) · info · success ✓
+ *     · wait ○ · ready ▶ · step • (info) · debug ◦ (debug) · trace » (trace).
+ *     warnOnce fires once per message and scope (memory bounded).
  *
- * Time — LOG_TIME=1|0, or setLogTime(). Default: on in Node record mode,
- *     off everywhere else (human eyes don't need stamps; browser and Worker
- *     consoles stamp lines themselves). Record time opens the line with UTC
- *     RFC3339; human time prefixes a dim local HH:MM:SS (a human knows
- *     today's date).
+ * Scopes
+ *     log.scope("api").scope("auth") carries ["api", "auth"]. Its threshold
+ *     is read live from API_AUTH_LOG_LEVEL, then API_LOG_LEVEL, then
+ *     LOG_LEVEL, then setLogLevel(), then info. Levels:
+ *     silent < error < warn < info < debug < trace.
  *
- * The record line with time on, identical across go-utils and py-utils by
- * design:
- *     2026-08-07T12:34:56Z WARN  [scope] message
- *     UTC RFC3339 seconds precision · level word padded to 5 · scope brackets
- *     only when scoped · no color, no symbols. Grep WARN, not ⚠.
+ * Spans
+ *     A span is a piece of work written as two events (start, end) and a
+ *     span is a logger: what is written through it carries its span_id and
+ *     trace_id, nothing else does. There is no ambient context.
+ *         await log.span("sync", { repo }, async (s) => {
+ *           s.info("cloned", { files })
+ *           await s.span("build", async (c) => { ... })
+ *           s.set({ pushed: true })
+ *         })
+ *     span returns what fn returns; a throw ends the span failed (the error
+ *     in fields.err) and rethrows. The open form, for work that does not fit
+ *     a block: const s = log.begin("upload", { size }) ... s.end() or
+ *     s.end(err). Ending twice, or set() after the end, panics.
+ *     Whether a span is shown is decided once, at begin, by its start's level
+ *     against its scope's threshold; the end follows, so a hidden span writes
+ *     no end, failed or not. What a hidden span holds attaches to the nearest
+ *     shown span, a joined remote one included: its lines carry that id, its
+ *     children and its traceparent() name it. With no shown ancestor its
+ *     lines carry no ids. A viewer never meets a missing parent.
  *
- * Sinks
- *     Node/Bun/Deno: every level writes to stderr through console.error, so
- *     stdout stays clean for data and cli/live's console routing keeps log
- *     lines above an active region.
- *     Browser: level-mapped console methods (debug/info/warn/error), human.
- *     Workers: level-mapped console methods, record.
+ * Traces cross processes explicitly
+ *     s.traceparent() is the W3C value to hand on (HTTP header, or the
+ *     TRACEPARENT env of a child). log.join(value) returns a logger whose
+ *     spans are children of that remote span; its lines outside a span carry
+ *     no ids. null/undefined returns the logger itself; a malformed value is
+ *     ignored with one warn per distinct value. TRACEPARENT in the
+ *     environment at process start is joined by every root span.
  *
- * Levels vs verbs
- *     Levels filter: silent < error < warn < info < debug < trace. An unknown
- *     LOG_LEVEL is a misconfiguration and throws Panic.
- *     Verbs express outcome and are renderings, never levels:
- *     error ⨯  fail ⨯ (error) · warn ⚠ (warn) · info · success ✓ · wait ○ ·
- *     ready ▶ · step • (info) · debug ◦ (debug) · trace » (trace).
- *     In record mode a verb renders as its level word.
+ * Renderings
+ *     json: one event per line, keys in the contract's order, fields sorted
+ *     at every depth. human: symbols, colour (TTY, NO_COLOR, FORCE_COLOR),
+ *     fields dim as key=value, an error's stack under its line, spans as
+ *     "○ name" ... "✓ name 254ms" with what they hold indented.
+ *     Default: Node/Bun/Deno human when stderr is a TTY, else json; browser
+ *     human; Worker json.
  *
- * Scopes
- *     log.scope('api') returns a child whose lines carry [api]; scopes nest
- *     and join: log.scope('api').scope('auth') → [api auth]. A scoped logger
- *     resolves its threshold from {SCOPE}_LOG_LEVEL (upper-cased, joined and
- *     sanitized to A-Z0-9_: API_AUTH_LOG_LEVEL, then API_LOG_LEVEL), falling
- *     back to setLogLevel(), then LOG_LEVEL, then info — read live, so one
- *     subsystem can be silenced or opened up without touching code.
+ * Configuration
+ *     Each variable has a setter; the setter is the program's default and the
+ *     variable, read live, overrides it: LOG_FORMAT=human|json (setLogFormat),
+ *     LOG_TIME=1|0 (setLogTime, a dim local HH:MM:SS before human lines, off
+ *     by default), LOG_LEVEL and {SCOPE}_LOG_LEVEL (setLogLevel), LOG_SERVICE
+ *     (setLogService). Values match without regard to case, an empty variable
+ *     is unset, an unknown value panics. The service defaults to the entry
+ *     script's name without extension; in a Worker or browser it must be
+ *     set, or the first json event panics.
  *
- * Config is env plus three runtime setters — setLogLevel(), setLogFormat(),
- *     setLogTime(). No handlers, no formatters, no init. NO_COLOR /
- *     FORCE_COLOR override color within human mode. Unknown values of any
- *     knob throw Panic. All internal memory is bounded.
+ * Sinks
+ *     Node/Bun/Deno write every event through console.error: stderr is the
+ *     log, stdout stays data, and cli/live's console patch keeps lines above
+ *     a live region. Browsers and Workers use the level's console method.
  *
- * Siblings: go-utils and py-utils implement the same doctrine in their own
- * idioms; the record line format is identical by design.
+ * The wire shape is exported as LogEvent, and parseEvent(line) reads one back.
  */
-import { panic } from "../offensive.js";
+import { assert, panic, SourcedError } from "../offensive.js";
 import { runtime } from "../runtime.js";
 import { BOLD, DIM, fg, RESET } from "./ansi.js";
+const EVENT_KEYS = [
+    "time",
+    "level",
+    "verb",
+    "msg",
+    "service",
+    "scope",
+    "phase",
+    "trace_id",
+    "span_id",
+    "parent_id",
+    "status",
+    "dur_ms",
+    "fields",
+];
+// --- verbs and levels ------------------------------------------------------
+const LEVELS = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+    trace: 5,
+};
+const VERBS = {
+    error: { level: "error", symbol: "⨯", style: BOLD + fg(1), indent: "" },
+    fail: { level: "error", symbol: "⨯", style: BOLD + fg(1), indent: "" },
+    warn: { level: "warn", symbol: "⚠", style: BOLD + fg(3), indent: "" },
+    info: { level: "info", symbol: " ", style: "", indent: "" },
+    success: { level: "info", symbol: "✓", style: BOLD + fg(2), indent: "" },
+    wait: { level: "info", symbol: "○", style: BOLD + fg(7), indent: "" },
+    ready: { level: "info", symbol: "▶", style: BOLD + fg(2), indent: "" },
+    step: { level: "info", symbol: "•", style: DIM, indent: "  " },
+    debug: { level: "debug", symbol: "◦", style: fg(8), indent: "" },
+    trace: { level: "trace", symbol: "»", style: BOLD + fg(5), indent: "" },
+};
+const isLogLevel = (s) => Object.hasOwn(LEVELS, s);
+const isVerb = (s) => Object.hasOwn(VERBS, s);
 const sink = runtime.isNode || runtime.isBun || runtime.isDeno
     ? "node"
     : runtime.isBrowser
         ? "browser"
         : "worker";
-let formatOverride;
-/** Force human or record rendering at runtime. Wins over LOG_FORMAT and auto-detection. */
+// An empty variable reads as unset: `LOG_LEVEL= cmd` is how a shell unsets one.
+const env = (key) => runtime.env(key) || undefined;
+// Values match without regard to case, from the environment and from code alike.
+function parseLevel(raw, source) {
+    const level = String(raw).toLowerCase();
+    if (!isLogLevel(level))
+        panic(`unknown ${source}:`, raw, "(want silent|error|warn|info|debug|trace)");
+    return level;
+}
+function parseFormat(raw, source) {
+    const format = String(raw).toLowerCase();
+    if (format !== "human" && format !== "json")
+        panic(`unknown ${source}:`, raw, "(want human|json)");
+    return format;
+}
+// Each setter is the program's default; the variable, read live, overrides it.
+let levelSetting;
+let formatSetting;
+let timeSetting;
+let serviceSetting;
+/** The program's default level. LOG_LEVEL and {SCOPE}_LOG_LEVEL override it. */
+export function setLogLevel(level) {
+    levelSetting = parseLevel(level, "log level");
+}
+/** The program's default rendering, human or json. LOG_FORMAT overrides it. */
 export function setLogFormat(format) {
-    if (format !== "human" && format !== "record")
-        panic("unknown log format:", format, "(want human|record)");
-    formatOverride = format;
+    formatSetting = parseFormat(format, "log format");
 }
+/** A dim local HH:MM:SS before human lines (json always carries time). LOG_TIME overrides it. */
+export function setLogTime(on) {
+    if (typeof on !== "boolean")
+        panic("setLogTime wants a boolean, got:", on);
+    timeSetting = on;
+}
+/** The program's name in every event. LOG_SERVICE overrides it. */
+export function setLogService(name) {
+    if (typeof name !== "string" || name.length === 0)
+        panic("setLogService wants a non-empty name, got:", name);
+    serviceSetting = name;
+}
+const scopeVar = (scope) => `${scope.map((s) => s.toUpperCase().replace(/[^A-Z0-9]+/g, "_")).join("_")}_LOG_LEVEL`;
+// Read live on every event, so an operator can open one subsystem without a restart.
+function threshold(scope) {
+    for (let i = scope.length; i > 0; i--) {
+        const name = scopeVar(scope.slice(0, i));
+        const raw = env(name);
+        if (raw !== undefined)
+            return LEVELS[parseLevel(raw, name)];
+    }
+    const raw = env("LOG_LEVEL");
+    if (raw !== undefined)
+        return LEVELS[parseLevel(raw, "LOG_LEVEL")];
+    return LEVELS[levelSetting ?? "info"];
+}
+const admits = (scope, level) => LEVELS[level] <= threshold(scope);
 function currentFormat() {
-    if (formatOverride)
-        return formatOverride;
-    const env = runtime.env("LOG_FORMAT");
-    if (env === "human" || env === "record")
-        return env;
-    if (env !== undefined)
-        panic("unknown LOG_FORMAT:", env, "(want human|record)");
+    const raw = env("LOG_FORMAT");
+    if (raw !== undefined)
+        return parseFormat(raw, "LOG_FORMAT");
+    if (formatSetting)
+        return formatSetting;
     if (sink === "node")
-        return runtime.stderr.isTTY ? "human" : "record";
-    return sink === "browser" ? "human" : "record";
-}
-// --- time ----------------------------------------------------------------
-let timeOverride;
-/** Force time prefixes on or off at runtime. Wins over LOG_TIME and the defaults. */
-export function setLogTime(on) {
-    timeOverride = on;
+        return runtime.stderr.isTTY ? "human" : "json";
+    return sink === "browser" ? "human" : "json";
 }
-// Default: on only for Node record mode. Human lines are for eyes; browser
-// and Worker consoles stamp every line themselves.
-function timeEnabled(format) {
-    if (timeOverride !== undefined)
-        return timeOverride;
-    const env = runtime.env("LOG_TIME");
-    if (env === "1")
+function timeEnabled() {
+    const raw = env("LOG_TIME");
+    if (raw === undefined)
+        return timeSetting ?? false;
+    if (raw === "1")
         return true;
-    if (env === "0")
+    if (raw === "0")
         return false;
-    if (env !== undefined)
-        panic("unknown LOG_TIME:", env, "(want 1|0)");
-    return format === "record" && sink === "node";
+    return panic("unknown LOG_TIME:", raw, "(want 1|0)");
+}
+function service() {
+    const named = env("LOG_SERVICE") ?? serviceSetting;
+    if (named !== undefined)
+        return named;
+    const entry = runtime.entry();
+    if (entry === undefined)
+        panic("log service unknown: a Worker or browser must set LOG_SERVICE or call setLogService()");
+    const base = entry.split(/[\\/]/).pop() ?? "";
+    const name = base.replace(/\.[^.]*$/, "") || base;
+    assert(name.length > 0, "log service: no name in entry", entry);
+    return name;
 }
 function colorEnabled() {
-    if (currentFormat() === "record")
-        return false;
     if (runtime.env("NO_COLOR"))
         return false;
     if (runtime.env("FORCE_COLOR"))
@@ -113,76 +218,237 @@ function colorEnabled() {
         return false;
     return runtime.stderr.isTTY && runtime.env("TERM") !== "dumb";
 }
-// --- levels --------------------------------------------------------------
-const LEVELS = {
-    silent: 0,
-    error: 1,
-    warn: 2,
-    info: 3,
-    debug: 4,
-    trace: 5,
-};
-function parseLevel(raw) {
-    const n = LEVELS[raw.toLowerCase()];
-    if (n === undefined)
-        panic("unknown log level:", raw, "(want silent|error|warn|info|debug|trace)");
-    return n;
+// --- ids and traceparent ---------------------------------------------------
+// W3C forbids an all-zero id; at 64 bits a redraw is a formality.
+function randomHex(bytes) {
+    for (;;) {
+        const b = crypto.getRandomValues(new Uint8Array(bytes));
+        if (b.some((x) => x !== 0))
+            return Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+    }
 }
-let levelOverride;
-/** Set the global log level at runtime. Wins over LOG_LEVEL; per-scope env vars still win over this. */
-export function setLogLevel(level) {
-    levelOverride = parseLevel(level);
+const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/;
+function parseTraceparent(value) {
+    const m = TRACEPARENT_RE.exec(value.trim());
+    if (!m)
+        return undefined;
+    const [, version, trace, span] = m;
+    if (version === "ff" || /^0+$/.test(trace) || /^0+$/.test(span))
+        return undefined;
+    return { trace, span };
 }
-const envKey = (scopes) => `${scopes
-    .map((s) => s.toUpperCase().replace(/[^A-Z0-9]+/g, "_"))
-    .join("_")}_LOG_LEVEL`;
-// Most specific scope wins: [api auth] reads API_AUTH_LOG_LEVEL, then
-// API_LOG_LEVEL, then the runtime override, then LOG_LEVEL. Read live on
-// every line so a level flip needs no restart hook.
-function threshold(scopes) {
-    for (let i = scopes.length; i > 0; i--) {
-        const raw = runtime.env(envKey(scopes.slice(0, i)));
-        if (raw !== undefined)
-            return parseLevel(raw);
+// Read once at load: the environment the process started with.
+const PROCESS_TRACEPARENT = env("TRACEPARENT");
+const PROCESS_PARENT = PROCESS_TRACEPARENT === undefined
+    ? undefined
+    : parseTraceparent(PROCESS_TRACEPARENT);
+let processTraceparentWarned = false;
+// Lexicographic by code point, as Go (UTF-8 bytes) and Python sort. JS string
+// comparison is by UTF-16 unit, which disagrees once a surrogate meets U+E000..U+FFFF.
+const lift = (c) => c >= 0xd800 && c <= 0xdfff ? c + 0x2000 : c >= 0xe000 ? c - 0x800 : c;
+function byCodePoint(a, b) {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        const x = a.charCodeAt(i);
+        const y = b.charCodeAt(i);
+        if (x !== y)
+            return lift(x) - lift(y);
     }
-    if (levelOverride !== undefined)
-        return levelOverride;
-    const raw = runtime.env("LOG_LEVEL");
-    return raw === undefined ? LEVELS.info : parseLevel(raw);
+    return a.length - b.length;
 }
-const VERBS = {
-    error: { level: "error", symbol: "⨯", style: BOLD + fg(1), indent: "" },
-    fail: { level: "error", symbol: "⨯", style: BOLD + fg(1), indent: "" },
-    warn: { level: "warn", symbol: "⚠", style: BOLD + fg(3), indent: "" },
-    info: { level: "info", symbol: " ", style: "", indent: "" },
-    success: { level: "info", symbol: "✓", style: BOLD + fg(2), indent: "" },
-    wait: { level: "info", symbol: "○", style: BOLD + fg(7), indent: "" },
-    ready: { level: "info", symbol: "▶", style: BOLD + fg(2), indent: "" },
-    step: { level: "info", symbol: "•", style: DIM, indent: "  " },
-    debug: { level: "debug", symbol: "◦", style: fg(8), indent: "" },
-    trace: { level: "trace", symbol: "»", style: BOLD + fg(5), indent: "" },
-};
-const LEVEL_WORD = {
-    error: "ERROR",
-    warn: "WARN ",
-    info: "INFO ",
-    debug: "DEBUG",
-    trace: "TRACE",
-};
-// --- rendering -----------------------------------------------------------
-const rfc3339 = () => `${new Date().toISOString().slice(0, 19)}Z`;
-const clockTime = () => new Date().toTimeString().slice(0, 8);
-function stringify(m) {
-    if (typeof m === "string")
-        return m;
-    if (m instanceof Error)
-        return m.stack ?? String(m);
+function sortedObject(entries, ancestors) {
+    const kept = Array.from(entries).filter(([, v]) => v !== undefined);
+    kept.sort(([a], [b]) => byCodePoint(a, b));
+    return new Map(kept.map(([k, v]) => [k, toNode(v, ancestors)]));
+}
+function base64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(binary);
+}
+const errorType = (e) => e.constructor.name || e.name;
+function typeName(v) {
+    if (v === null)
+        return "null";
+    if (typeof v !== "object")
+        return typeof v;
+    return (v.constructor?.name || "Object");
+}
+// type, message, then when present stack, cause, and a SourcedError's
+// source, operation, status, context. An error's own keys keep this order.
+function errorNode(e, ancestors) {
+    const node = new Map([
+        ["type", errorType(e)],
+        ["message", String(e.message)],
+    ]);
+    if (typeof e.stack === "string")
+        node.set("stack", e.stack);
+    if (e.cause !== undefined && e.cause !== null) {
+        const cause = e.cause;
+        node.set("cause", cause instanceof Error
+            ? toNode(cause, ancestors)
+            : new Map([
+                ["type", typeName(cause)],
+                [
+                    "message",
+                    typeof cause === "object"
+                        ? encode(toNode(cause, ancestors))
+                        : String(cause),
+                ],
+            ]));
+    }
+    if (e instanceof SourcedError) {
+        node.set("source", e.source);
+        node.set("operation", e.operation);
+        if (e.status !== undefined)
+            node.set("status", e.status);
+        if (Object.keys(e.context).length > 0)
+            node.set("context", toNode(e.context, ancestors));
+    }
+    return node;
+}
+/** A field value as JSON, by the contract's table. */
+function toNode(v, ancestors) {
+    if (v === null || typeof v === "string" || typeof v === "boolean")
+        return v;
+    if (typeof v === "number")
+        return Number.isFinite(v) ? v : String(v);
+    if (typeof v === "bigint")
+        return v.toString();
+    if (typeof v !== "object")
+        return String(v);
+    if (ancestors.has(v))
+        return "[circular]";
+    if (v instanceof Date)
+        return Number.isNaN(v.getTime()) ? String(v) : v.toISOString();
+    if (v instanceof Uint8Array)
+        return base64(v);
+    if (v instanceof ArrayBuffer)
+        return base64(new Uint8Array(v));
+    ancestors.add(v);
     try {
-        return JSON.stringify(m) ?? String(m);
+        if (v instanceof Error)
+            return errorNode(v, ancestors);
+        if (Array.isArray(v))
+            return v.map((x) => (x === undefined ? null : toNode(x, ancestors)));
+        if (v instanceof Map)
+            return sortedObject(Array.from(v, ([k, x]) => [String(k), x]), ancestors);
+        if (v instanceof Set)
+            return Array.from(v, (x) => x === undefined ? null : toNode(x, ancestors));
+        const toJSON = v.toJSON;
+        if (typeof toJSON === "function")
+            return toNode(toJSON.call(v), ancestors);
+        return sortedObject(Object.entries(v), ancestors);
     }
-    catch {
-        return String(m);
+    finally {
+        ancestors.delete(v);
+    }
+}
+function encode(n) {
+    if (n === null)
+        return "null";
+    if (typeof n === "string" || typeof n === "number")
+        return JSON.stringify(n);
+    if (typeof n === "boolean")
+        return n ? "true" : "false";
+    if (Array.isArray(n))
+        return `[${n.map(encode).join(",")}]`;
+    const parts = [];
+    for (const [k, v] of n)
+        parts.push(`${JSON.stringify(k)}:${encode(v)}`);
+    return `{${parts.join(",")}}`;
+}
+const isPlainObject = (v) => {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+};
+function assertFields(fields) {
+    assert(fields === undefined || isPlainObject(fields), "log fields must be a plain object (message, { key: value }), got", typeName(fields));
+}
+const round3 = (ms) => Math.round(ms * 1000) / 1000;
+function json(d, now) {
+    const level = VERBS[d.verb].level;
+    let s = `{"time":"${now.toISOString()}","level":"${level}","verb":"${d.verb}","msg":${JSON.stringify(d.msg)},"service":${JSON.stringify(service())}`;
+    if (d.scope.length > 0)
+        s += `,"scope":${encode([...d.scope])}`;
+    if (d.phase)
+        s += `,"phase":"${d.phase}"`;
+    if (d.trace)
+        s += `,"trace_id":"${d.trace}"`;
+    if (d.span)
+        s += `,"span_id":"${d.span}"`;
+    if (d.parent)
+        s += `,"parent_id":"${d.parent}"`;
+    if (d.status)
+        s += `,"status":"${d.status}"`;
+    if (d.dur !== undefined)
+        s += `,"dur_ms":${round3(d.dur)}`;
+    if (d.fields) {
+        const node = sortedObject(Object.entries(d.fields), new Set());
+        if (node.size > 0)
+            s += `,"fields":${encode(node)}`;
+    }
+    return `${s}}`;
+}
+function humanDuration(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const s = Math.round(ms / 1000);
+    return `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`;
+}
+const quoted = (s) => s === "" || /[\s"=]/.test(s) ? JSON.stringify(s) : s;
+const errorLine = (e) => e instanceof SourcedError
+    ? `${errorType(e)} [${e.source}:${e.operation}${e.status === undefined ? "" : ` ${e.status}`}]: ${e.message}`
+    : `${errorType(e)}: ${e.message}`;
+function humanValue(v) {
+    if (v instanceof Error)
+        return quoted(errorLine(v));
+    const node = toNode(v, new Set());
+    return typeof node === "string" ? quoted(node) : encode(node);
+}
+// The stack minus its "Name: message" head (already on the line), then each cause.
+function stackLines(e) {
+    const lines = [];
+    const seen = new Set();
+    let at = e;
+    while (at instanceof Error && !seen.has(at)) {
+        seen.add(at);
+        if (at !== e)
+            lines.push(`caused by ${errorLine(at)}`);
+        const stack = at.stack ?? "";
+        const head = String(at);
+        const body = stack.startsWith(head) ? stack.slice(head.length) : stack;
+        for (const l of body.split("\n"))
+            if (l.trim())
+                lines.push(l.trim());
+        at = at.cause;
     }
+    return lines;
+}
+function human(d, now, clock) {
+    const v = VERBS[d.verb];
+    const color = colorEnabled();
+    const paint = (style, s) => color && style ? `${style}${s}${RESET}` : s;
+    const pad = "  ".repeat(d.depth);
+    const stamp = clock ? `${paint(DIM, now.toTimeString().slice(0, 8))} ` : "";
+    const scope = d.scope.length > 0 ? `${paint(DIM, `[${d.scope.join(" ")}]`)} ` : "";
+    const dur = d.dur === undefined ? "" : ` ${paint(DIM, humanDuration(d.dur))}`;
+    const pairs = Object.entries(d.shows ?? d.fields ?? {})
+        .filter(([, x]) => x !== undefined)
+        .sort(([a], [b]) => byCodePoint(a, b));
+    const tail = pairs.length > 0
+        ? ` ${paint(DIM, pairs.map(([k, x]) => `${k}=${humanValue(x)}`).join(" "))}`
+        : "";
+    const head = `${stamp}${pad}${v.indent} ${paint(v.style, v.symbol)} ${scope}${d.msg}${dur}${tail}`;
+    const stacks = pairs.flatMap(([, x]) => x instanceof Error
+        ? stackLines(x).map((l) => paint(DIM, `${pad}    ${l}`))
+        : []);
+    return [head, ...stacks].join("\n");
 }
 const CONSOLE_METHOD = {
     error: "error",
@@ -191,44 +457,148 @@ const CONSOLE_METHOD = {
     debug: "debug",
     trace: "debug",
 };
-function emit(scopes, verb, messages) {
-    const v = VERBS[verb];
-    if (LEVELS[v.level] > threshold(scopes))
-        return;
-    // Node funnels every level through console.error: stderr is the log sink
-    // and cli/live patches console methods to reroute lines above an active
-    // region. Browser/worker use level-mapped methods so platform consoles
-    // classify lines correctly.
-    const method = sink === "node" ? "error" : CONSOLE_METHOD[v.level];
+// The caller has already decided the event passes its threshold.
+function emit(d) {
+    const now = new Date();
+    // Every knob is read on every event, so a bad value screams whichever rendering is on.
     const format = currentFormat();
-    if (format === "record") {
-        const stamp = timeEnabled(format) ? `${rfc3339()} ` : "";
-        const scope = scopes.length > 0 ? `[${scopes.join(" ")}] ` : "";
-        console[method](`${stamp}${LEVEL_WORD[v.level]} ${scope}${messages.map(stringify).join(" ")}`);
-        return;
-    }
-    const color = colorEnabled();
-    const dimmed = (s) => (color ? `${DIM}${s}${RESET}` : s);
-    const stamp = timeEnabled(format) ? `${dimmed(clockTime())} ` : "";
-    const symbol = color ? `${v.style}${v.symbol}${RESET}` : v.symbol;
-    const scope = scopes.length > 0 ? `${dimmed(`[${scopes.join(" ")}]`)} ` : "";
-    const prefix = `${stamp}${v.indent} ${symbol} ${scope}`;
-    // A single string collapses into one line; anything richer is handed to
-    // console so devtools/util.inspect keep live object rendering.
-    if (messages.length === 1 && typeof messages[0] === "string") {
-        console[method](`${prefix}${messages[0]}`);
-    }
-    else {
-        console[method](prefix.trimEnd(), ...messages);
-    }
+    const clock = timeEnabled();
+    const text = format === "json" ? json(d, now) : human(d, now, clock);
+    // Node: everything to stderr through console.error, which cli/live patches
+    // to keep lines above an active region. Elsewhere the level's method, so
+    // platform consoles classify the line.
+    if (sink === "node")
+        console.error(text);
+    else
+        console[CONSOLE_METHOD[VERBS[d.verb].level]](text);
 }
-// --- bounded state (daemons run for months) ------------------------------
 const BOUND = 1024;
 const warned = new Set();
-const timers = new Map();
-function makeLogger(scopes) {
-    const verb = (v) => (...messages) => emit(scopes, v, messages);
-    return {
+const badTraceparents = new Set();
+function line(ctx, verb, message, fields) {
+    assert(typeof message === "string", "log message must be a string, got", typeName(message));
+    assertFields(fields);
+    if (!admits(ctx.scope, VERBS[verb].level))
+        return;
+    emit({
+        verb,
+        msg: message,
+        scope: ctx.scope,
+        depth: ctx.depth,
+        trace: ctx.owner === undefined ? undefined : ctx.trace,
+        span: ctx.owner,
+        fields,
+    });
+}
+function open(ctx, name, initial) {
+    assert(typeof name === "string" && name.length > 0, "span name must be a non-empty string, got", typeName(name));
+    assertFields(initial);
+    let remote;
+    if (ctx.trace === undefined) {
+        remote = PROCESS_PARENT;
+        if (PROCESS_TRACEPARENT !== undefined &&
+            !remote &&
+            !processTraceparentWarned) {
+            processTraceparentWarned = true;
+            line(ctx, "warn", "malformed TRACEPARENT ignored", {
+                traceparent: PROCESS_TRACEPARENT,
+            });
+        }
+    }
+    const trace = ctx.trace ?? remote?.trace ?? randomHex(16);
+    const parent = ctx.trace === undefined ? remote?.span : ctx.parent;
+    const id = randomHex(8);
+    // Decided once, here: the start's level against the scope's threshold now.
+    const shown = admits(ctx.scope, "info");
+    const began = performance.now();
+    const fields = { ...initial };
+    let added = {};
+    let ended = false;
+    if (shown)
+        emit({
+            verb: "wait",
+            msg: name,
+            scope: ctx.scope,
+            depth: ctx.depth,
+            phase: "start",
+            trace,
+            span: id,
+            parent,
+            fields,
+        });
+    // A hidden span is transparent: its lines and children attach to the nearest
+    // shown span, a joined remote one included (it is shown in its own process's
+    // stream). With none, its lines carry no ids, as lines outside any span.
+    const inner = shown
+        ? { scope: ctx.scope, depth: ctx.depth + 1, trace, parent: id, owner: id }
+        : { scope: ctx.scope, depth: ctx.depth, trace, parent, owner: parent };
+    return Object.assign(makeLogger(inner), {
+        set(more) {
+            assert(!ended, "span", name, "got set() after it ended");
+            assertFields(more);
+            added = { ...added, ...more };
+        },
+        // A hidden span hands on the nearest shown span (local or joined), its own id only with none.
+        traceparent() {
+            return `00-${trace}-${shown ? id : (parent ?? id)}-01`;
+        },
+        end(err) {
+            assert(!ended, "span", name, "ended twice");
+            ended = true;
+            // The end follows the decision made at begin: no end without its start.
+            if (!shown)
+                return;
+            const dur = performance.now() - began;
+            const failed = err !== undefined && err !== null;
+            const shows = failed ? { ...added, err } : added;
+            emit({
+                verb: failed ? "fail" : "success",
+                msg: name,
+                scope: ctx.scope,
+                depth: ctx.depth,
+                phase: "end",
+                trace,
+                span: id,
+                parent,
+                status: failed ? "error" : "ok",
+                dur,
+                fields: { ...fields, ...shows },
+                shows,
+            });
+        },
+    });
+}
+const isThenable = (v) => typeof v?.then === "function";
+function makeLogger(ctx) {
+    const verb = (v) => (message, fields) => line(ctx, v, message, fields);
+    function span(name, a, b) {
+        const fn = typeof a === "function" ? a : b;
+        const fields = typeof a === "function" ? undefined : a;
+        assert(typeof fn === "function", "span", name, "needs a function");
+        const s = open(ctx, name, fields);
+        // end(null) means ok; a block that threw null still failed.
+        const failed = (e) => e ?? String(e);
+        let result;
+        try {
+            result = fn(s);
+        }
+        catch (e) {
+            s.end(failed(e));
+            throw e;
+        }
+        if (!isThenable(result)) {
+            s.end();
+            return result;
+        }
+        return Promise.resolve(result).then((v) => {
+            s.end();
+            return v;
+        }, (e) => {
+            s.end(failed(e));
+            throw e;
+        });
+    }
+    const logger = {
         error: verb("error"),
         fail: verb("fail"),
         warn: verb("warn"),
@@ -239,57 +609,147 @@ function makeLogger(scopes) {
         step: verb("step"),
         debug: verb("debug"),
         trace: verb("trace"),
-        warnOnce(...messages) {
-            const key = scopes.join(" ") + messages.map(stringify).join(" ");
+        warnOnce(message, fields) {
+            const key = `${ctx.scope.join("\0")}\0${message}`;
             if (warned.has(key))
                 return;
             if (warned.size >= BOUND)
                 warned.clear();
             warned.add(key);
-            emit(scopes, "warn", messages);
+            line(ctx, "warn", message, fields);
         },
-        time(label) {
-            if (timers.size >= BOUND)
-                timers.clear();
-            timers.set(`${scopes.join(" ")}:${label}`, Date.now());
+        scope(name) {
+            assert(typeof name === "string" && name.length > 0, "scope name must be a non-empty string, got", typeName(name));
+            return makeLogger({ ...ctx, scope: [...ctx.scope, name] });
         },
-        timeEnd(label) {
-            const key = `${scopes.join(" ")}:${label}`;
-            const start = timers.get(key);
-            if (start === undefined) {
-                emit(scopes, "warn", [`Timer '${label}' does not exist`]);
-                return;
-            }
-            timers.delete(key);
-            const ms = Date.now() - start;
-            const pretty = ms > 10_000 ? `${Math.round(ms / 100) / 10}s` : `${Math.round(ms)}ms`;
-            emit(scopes, "trace", [`${label}: ${pretty}`]);
+        span,
+        begin(name, fields) {
+            return open(ctx, name, fields);
         },
-        scope(name) {
-            return makeLogger([...scopes, name]);
+        join(traceparent) {
+            if (traceparent === null || traceparent === undefined)
+                return logger;
+            const remote = typeof traceparent === "string"
+                ? parseTraceparent(traceparent)
+                : undefined;
+            if (!remote) {
+                // Input from outside: one warn per distinct value, memory bounded.
+                const value = String(traceparent);
+                if (!badTraceparents.has(value)) {
+                    if (badTraceparents.size >= BOUND)
+                        badTraceparents.clear();
+                    badTraceparents.add(value);
+                    line(ctx, "warn", "malformed traceparent ignored", {
+                        traceparent: value,
+                    });
+                }
+                return logger;
+            }
+            return makeLogger({
+                scope: ctx.scope,
+                depth: ctx.depth,
+                trace: remote.trace,
+                parent: remote.span,
+                owner: undefined,
+            });
         },
     };
+    return logger;
+}
+/** The root logger. */
+export const log = makeLogger({
+    scope: [],
+    depth: 0,
+    trace: undefined,
+    parent: undefined,
+    owner: undefined,
+});
+// --- reading the stream ----------------------------------------------------
+const TIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const HEX32 = /^[0-9a-f]{32}$/;
+const HEX16 = /^[0-9a-f]{16}$/;
+/**
+ * One line of a stream as an event, or null for a line that is not one (a
+ * runtime panic, a library writing to stderr itself) so a viewer can pass it
+ * through. A JSON object with a "verb" key claims to be an event: if it
+ * breaks the contract's shape, that is a bug in a writer and it panics.
+ */
+export function parseEvent(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("{"))
+        return null;
+    let value;
+    try {
+        value = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (!isPlainObject(value) || !Object.hasOwn(value, "verb"))
+        return null;
+    const e = value;
+    const bad = (why) => panic("malformed log event:", why, "in", trimmed);
+    const has = (k) => Object.hasOwn(e, k);
+    const keys = Object.keys(e);
+    for (const k of keys)
+        if (!EVENT_KEYS.includes(k))
+            bad(`unknown key "${k}"`);
+    const order = EVENT_KEYS.filter(has);
+    if (keys.join() !== order.join())
+        bad(`keys out of order: ${keys.join(",")}`);
+    for (const k of ["time", "level", "verb", "msg", "service"])
+        if (!has(k))
+            bad(`missing "${k}"`);
+    if (typeof e.time !== "string" || !TIME_RE.test(e.time))
+        bad("time");
+    if (typeof e.verb !== "string" || !isVerb(e.verb))
+        bad("verb");
+    const verb = e.verb;
+    if (e.level !== VERBS[verb].level)
+        bad(`level of verb ${verb}`);
+    if (typeof e.msg !== "string")
+        bad("msg");
+    if (typeof e.service !== "string" || e.service.length === 0)
+        bad("service");
+    if (has("scope") &&
+        !(Array.isArray(e.scope) &&
+            e.scope.length > 0 &&
+            e.scope.every((s) => typeof s === "string")))
+        bad("scope");
+    if (has("trace_id") &&
+        !(typeof e.trace_id === "string" && HEX32.test(e.trace_id)))
+        bad("trace_id");
+    for (const k of ["span_id", "parent_id"])
+        if (has(k) && !(typeof e[k] === "string" && HEX16.test(e[k])))
+            bad(k);
+    if (has("fields") && !isPlainObject(e.fields))
+        bad("fields");
+    if (has("span_id") && !has("trace_id"))
+        bad("span_id without trace_id");
+    if (has("parent_id") && !has("phase"))
+        bad("parent_id without phase");
+    if (has("phase")) {
+        if (e.phase !== "start" && e.phase !== "end")
+            bad("phase");
+        if (!has("trace_id") || !has("span_id"))
+            bad("span event without ids");
+    }
+    if (e.phase === "start") {
+        if (verb !== "wait")
+            bad("start verb");
+        if (has("status") || has("dur_ms"))
+            bad("start with status or dur_ms");
+    }
+    if (e.phase === "end") {
+        if (e.status !== "ok" && e.status !== "error")
+            bad("status");
+        if (typeof e.dur_ms !== "number" || !(e.dur_ms >= 0))
+            bad("dur_ms");
+        if (verb !== (e.status === "ok" ? "success" : "fail"))
+            bad("end verb");
+    }
+    else if (has("status") || has("dur_ms"))
+        bad("status or dur_ms outside an end");
+    return e;
 }
-const root = makeLogger([]);
-export const error = root.error;
-export const fail = root.fail;
-export const warn = root.warn;
-export const warnOnce = root.warnOnce;
-export const info = root.info;
-export const success = root.success;
-export const wait = root.wait;
-export const ready = root.ready;
-export const step = root.step;
-export const debug = root.debug;
-export const trace = root.trace;
-export const time = root.time;
-export const timeEnd = root.timeEnd;
-export const scope = root.scope;
-/** The root logger plus its runtime knobs, for namespace-style consumers. */
-export const log = {
-    ...root,
-    setLogLevel,
-    setLogFormat,
-    setLogTime,
-};
 //# sourceMappingURL=log.js.map