@telorun/kernel 0.48.0 → 0.50.0

package/src/kernel.ts

@@ -33,6 +33,10 @@ import { ControllerRegistry } from "./controller-registry.js";
 import { EventBus } from "./events.js";
 import { hostEnv, lockControllerEnv } from "./host-env.js";
 import { KernelTracer } from "./tracing.js";
+import { KernelLogging, type LoggingManifestBlock } from "./logging/kernel-logging.js";
+import type { ScopeConfig } from "./logging/scope-config.js";
+import { formatSpanCounter } from "./logging/span-id.js";
+import { ambientInvokeContext } from "./evaluation-context.js";
 import { ModuleContext } from "./module-context.js";
 import { ResourceContextImpl } from "./resource-context.js";
 import { nodeCelHandlers } from "./cel-handlers.js";
@@ -148,12 +152,36 @@ export class Kernel implements IKernel {
   readonly env: Record<string, string | undefined>;
   readonly argv: string[];
   readonly registryUrl: string | undefined;
+  /** Structured logging for this kernel — the pipeline, its sinks, and the
+   *  scoped loggers handed to controllers as `ctx.log`. Live from construction
+   *  so loader and parse diagnostics have somewhere to go (§12.3); a nested
+   *  kernel inherits the parent's sink configuration through the injected
+   *  streams, so a test harness can capture child output (§13.1). */
+  readonly logging: KernelLogging;
 
   constructor(options: KernelOptions) {
     this.stdin = options.stdin ?? process.stdin;
     this.stdout = options.stdout ?? process.stdout;
     this.stderr = options.stderr ?? process.stderr;
     this.env = options.env ?? hostEnv();
+    this.logging = new KernelLogging({
+      env: this.env,
+      stdout: this.stdout,
+      stderr: this.stderr,
+    });
+    // The validator is constructed outside the kernel's stdio scope, so it is
+    // handed the kernel logger explicitly rather than writing to process.stderr.
+    this.sharedSchemaValidator.setLogger(this.logging.kernelLogger());
+    // §7.2: a record emitted inside an active dispatch span carries that span's
+    // ids automatically — a controller never passes them. The ids come from the
+    // same counter the trace wire uses, rendered here at the encoding boundary.
+    this.logging.setTraceContextProvider(() => {
+      const ambient = ambientInvokeContext();
+      if (!ambient?.traceId || ambient.invocationId === undefined) return undefined;
+      const spanId = formatSpanCounter(ambient.invocationId);
+      if (!spanId) return undefined;
+      return { traceId: ambient.traceId, spanId };
+    });
     this.argv = options.argv ?? [];
     this.registryUrl = options.registryUrl;
     // Resolution sources come from the transport registry, so a scheme-owning
@@ -297,6 +325,18 @@ export class Kernel implements IKernel {
       "Telo.Import",
       await import("./controllers/module/import-controller.js"),
     );
+    // The mandatory sinks live in the kernel rather than in a standard-library
+    // module: §16 requires every conforming runtime to implement both, so
+    // shipping them as an installable module would make conformance depend on
+    // whether that module happened to be installed.
+    this.controllers.registerController(
+      "Telo.ConsoleSink",
+      await import("./controllers/logging/console-sink-controller.js"),
+    );
+    this.controllers.registerController(
+      "Telo.FileSink",
+      await import("./controllers/logging/file-sink-controller.js"),
+    );
   }
 
   /**
@@ -398,7 +438,9 @@ export class Kernel implements IKernel {
       );
     }
     for (const d of analysisGraph.versionDiagnostics) {
-      if (d.code === "MODULE_VERSION_HOISTED") console.warn(`warning: ${d.message}`);
+      if (d.code === "MODULE_VERSION_HOISTED") {
+        this.logging.kernelLogger().warn(d.message, { "telo.diagnostic.code": d.code });
+      }
     }
     const staticManifests = flattenForAnalyzer(analysisGraph);
     this.staticManifests = staticManifests;
@@ -461,9 +503,7 @@ export class Kernel implements IKernel {
       try {
         await writeAnalysisStamp("", analysisSignature, manifestsDir);
       } catch (err) {
-        this.stderr.write(
-          `[telo:kernel] analysis stamp write failed: ${err instanceof Error ? err.message : String(err)}\n`,
-        );
+        this.logging.kernelLogger().warn("analysis stamp write failed", undefined, { error: err });
       }
     }
 
@@ -601,9 +641,34 @@ export class Kernel implements IKernel {
         port,
         protocol: portDecls[name]?.protocol === "udp" ? "udp" : "tcp",
       }));
+
+      this.applyLoggingConfig(rootApplicationManifest as Record<string, any>);
     }
   }
 
+  /**
+   * Adopt the manifest's `logging:` block — §12.3's handover from the bootstrap
+   * default to the declared configuration.
+   *
+   * Deliberately runs *after* `variables` / `secrets` resolve, because the only
+   * sanctioned way to derive a level from the host environment is a `variables:`
+   * entry read with `!cel`: there is no `TELO_LOG_LEVEL`, so the expression must
+   * have something to resolve against by the time it is evaluated.
+   *
+   * Manifest secrets are handed to the pipeline here so they redact with no
+   * configuration at all (§14) — the same set, cascading down the same import
+   * graph, that supplies the scope threshold.
+   */
+  private applyLoggingConfig(rootApplicationManifest: Record<string, any>): void {
+    const raw = rootApplicationManifest["logging"];
+    if (raw === undefined) {
+      this.logging.applyRootConfig(undefined, this.rootContext.secretValues);
+      return;
+    }
+    const expanded = this.rootContext.expandWith(raw, {}) as LoggingManifestBlock;
+    this.logging.applyRootConfig(expanded, this.rootContext.secretValues);
+  }
+
   /**
    * Resolved inbound ports from the root Application's `ports:` block, available
    * after {@link load}. Each carries the resolved integer and its declared
@@ -642,10 +707,14 @@ export class Kernel implements IKernel {
     // return earlier — so analysis/editor are unaffected. The denied set is
     // process-global and additive across in-process kernels.
     lockControllerEnv(this._declaredEnvKeys, (key) => {
-      this.stderr.write(
-        `[telo] controller read process.env.${key} directly — ${key} is a declared ` +
-          `binding; read it through ctx.env or its variable/secret, not raw process.env.\n`,
-      );
+      this.logging
+        .kernelLogger()
+        .warn(
+          `controller read process.env.${key} directly — ${key} is a declared binding; ` +
+            `read it through ctx.env or its variable/secret, not raw process.env.`,
+          { "telo.env.key": key },
+          { eventName: "telo.env.declared_binding_bypassed" },
+        );
     });
 
     // Call register hooks for controllers actually loaded at this point (built-ins).
@@ -689,11 +758,26 @@ export class Kernel implements IKernel {
     }
 
     await this.rootContext.initializeResources();
+
+    // Every declared sink has now attached, so the bootstrap buffer has done its
+    // job. A consumer connecting later — the debug wire — wants the live stream,
+    // not the whole process history, so replay stops here rather than persisting
+    // for the process lifetime. The sink-counting and the tree walk are logging
+    // logic, so they live on KernelLogging; the kernel just hands it the graph.
+    this.logging.sealBootstrap(this.staticManifests);
+
     await this.eventBus.emit("Kernel.Initialized", {});
 
     this._isBooted = true;
   }
 
+  /** Every module context's resolved logging configuration, keyed by its dotted
+   *  import-alias path. Delegates to {@link KernelLogging.scopesFrom}; see there
+   *  for what §12.2 uses it for. */
+  loggingScopes(): Map<string, ScopeConfig> {
+    return this.logging.scopesFrom(this.rootContext);
+  }
+
   /**
    * Run the manifest's `targets` (Telo.Service / Telo.Runnable instances).
    * Emits Kernel.Starting before, Kernel.Started after.
@@ -749,6 +833,12 @@ export class Kernel implements IKernel {
     if (this.rootContext) {
       await this.rootContext.teardownResources();
     }
+    // Sinks tear down last (they are pinned in the teardown order), so by this
+    // point their own teardown has already flushed and closed them. This drains
+    // anything emitted during teardown itself and reports outstanding drop
+    // accounting, so a run that ends while still dropping does not lose its
+    // final count (§10.4, §10.5).
+    await this.logging.shutdown();
     // Drop the load-time graph so a teardown'd kernel doesn't pin every
     // manifest file's text in memory (LoadedFile retains the parsed
     // documents + the original YAML bytes). Reusing the kernel after

package/src/logging/bootstrap-writer.ts

@@ -0,0 +1,38 @@
+import { SEVERITY } from "@telorun/sdk";
+import { ConsoleSink } from "./console-sink.js";
+import type { LogSinkInstance } from "./log-sink.js";
+
+/**
+ * The pre-manifest console writer — `kernel/specs/logging.md` §12.3.
+ *
+ * Records emitted before the manifest is parsed — loader and parse diagnostics —
+ * cannot consult a `logging:` block that does not yet exist. During that phase
+ * the runtime uses a fixed default of `info` on an internal writer, and switches
+ * to the declared configuration as soon as the manifest resolves. This is the
+ * only phase not manifest-governed, and it is not configurable by other means.
+ *
+ * The writer is kernel-internal and is deliberately **not** a
+ * `Telo.ConsoleSink` resource — it exists precisely because no resource can yet.
+ * It is also what makes D3 hold: because the pre-manifest window is covered
+ * unconditionally, declared sinks are free to be resources that attach later,
+ * with buffered records replayed into them.
+ */
+
+export const BOOTSTRAP_SINK_ID = "<bootstrap>";
+
+export function createBootstrapWriter(options: {
+  env: Record<string, string | undefined>;
+  stdout: NodeJS.WritableStream;
+  stderr: NodeJS.WritableStream;
+}): LogSinkInstance {
+  return new ConsoleSink({
+    sinkId: BOOTSTRAP_SINK_ID,
+    level: SEVERITY.info,
+    destination: "stderr",
+    encoding: "auto",
+    color: "auto",
+    env: options.env,
+    stdout: options.stdout,
+    stderr: options.stderr,
+  });
+}

package/src/logging/color-precedence.ts

@@ -0,0 +1,62 @@
+/**
+ * Console color decision — `kernel/specs/logging.md` §11.2.
+ *
+ * The precedence order is normative and must be implemented exactly. Steps 2–7
+ * apply only under `color: auto`; `always` / `never` short-circuit at step 1.
+ *
+ * These environment inputs are **not** a second configuration channel and do not
+ * contradict D6. `NO_COLOR`, `FORCE_COLOR`, `TERM`, and `isatty()` describe the
+ * terminal's capability and the operator's preference, not the application's
+ * desired state: `auto` means "detect the environment", and the manifest remains
+ * the sole authority over *what* is logged — these affect only how it is
+ * painted.
+ */
+
+export type ColorSetting = "auto" | "always" | "never";
+
+export interface ColorDecisionInput {
+  /** The manifest's `color:` setting. */
+  setting: ColorSetting;
+  /** The environment to consult. Always the real host environment, never the
+   *  guardrail proxy — these are host capability signals, not bindings. */
+  env: Record<string, string | undefined>;
+  /** Whether the **sink's actual output descriptor** is a TTY. A console sink on
+   *  `stdout` and another on `stderr` can decide differently, and that is
+   *  correct — this is never the process's descriptor by proxy. */
+  isTTY: boolean;
+}
+
+export function decideColor(input: ColorDecisionInput): boolean {
+  const { setting, env, isTTY } = input;
+
+  // 1. An explicit manifest setting wins outright.
+  if (setting === "always") return true;
+  if (setting === "never") return false;
+
+  // 2. NO_COLOR: presence and non-emptiness matter, the value does not. Testing
+  //    mere presence is a widespread bug — `NO_COLOR=""` must NOT disable color.
+  if (isNonEmpty(env["NO_COLOR"])) return false;
+
+  // 3. FORCE_COLOR: "0" disables, any other non-empty value enables.
+  const forceColor = env["FORCE_COLOR"];
+  if (isNonEmpty(forceColor)) return forceColor !== "0";
+
+  // 4. CLICOLOR_FORCE present and not "0" enables.
+  const clicolorForce = env["CLICOLOR_FORCE"];
+  if (clicolorForce !== undefined && clicolorForce !== "0") return true;
+
+  // 5. CLICOLOR=0 disables.
+  if (env["CLICOLOR"] === "0") return false;
+
+  // 6. A dumb terminal cannot render color.
+  if (env["TERM"] === "dumb") return false;
+
+  // 7. Otherwise follow the descriptor. Note there is deliberately no CI-variable
+  //    branch: forcing color on merely because a CI variable is present is a
+  //    widespread bug in existing libraries, not a convention to copy.
+  return isTTY;
+}
+
+function isNonEmpty(value: string | undefined): boolean {
+  return value !== undefined && value !== "";
+}

package/src/logging/console-sink.ts

@@ -0,0 +1,86 @@
+import type { LogRecord } from "@telorun/sdk";
+import { decideColor, type ColorSetting } from "./color-precedence.js";
+import { encodeJsonLine, type BytesEncoder } from "./encode-json.js";
+import { encodePrettyLine } from "./encode-pretty.js";
+import type { LogSinkInstance } from "./log-sink.js";
+
+/**
+ * `Telo.ConsoleSink` — a kernel built-in (§10.2).
+ *
+ * Console and file are built-ins rather than standard-library modules because
+ * §16 already requires every conforming runtime to implement both, along with
+ * the `pretty` and `json` encodings, byte-identically. Mandatory runtime
+ * behaviour belongs in the runtime; shipping it as an installable module would
+ * make conformance depend on whether that module happened to be installed.
+ *
+ * Synchronous by default: a developer-facing stream that silently reorders or
+ * drops is worse than a slow one, and `on_full` does not apply to a sink with no
+ * buffer to saturate.
+ */
+
+export type ConsoleEncoding = "auto" | "pretty" | "json";
+export type ConsoleDestination = "stderr" | "stdout";
+
+export interface ConsoleSinkOptions {
+  sinkId: string;
+  level: number;
+  destination?: ConsoleDestination;
+  encoding?: ConsoleEncoding;
+  color?: ColorSetting;
+  /** The host environment — capability signals only, never a config channel. */
+  env: Record<string, string | undefined>;
+  stdout: NodeJS.WritableStream;
+  stderr: NodeJS.WritableStream;
+  encodeBytes?: BytesEncoder;
+}
+
+export class ConsoleSink implements LogSinkInstance {
+  readonly sinkId: string;
+  readonly level: number;
+  /** A file-descriptor write blocks until the bytes are handed to the OS, so a
+   *  `fatal` record is durable by the time `log()` returns (§10.5). */
+  readonly syncFlushable = true;
+
+  readonly #stream: NodeJS.WritableStream;
+  readonly #pretty: boolean;
+  readonly #color: boolean;
+  readonly #encodeBytes: BytesEncoder | undefined;
+
+  constructor(options: ConsoleSinkOptions) {
+    this.sinkId = options.sinkId;
+    this.level = options.level;
+    const destination = options.destination ?? "stderr";
+    this.#stream = destination === "stdout" ? options.stdout : options.stderr;
+
+    // `auto` is evaluated against *this sink's* destination descriptor, not the
+    // process's: a console sink on stdout and another on stderr can resolve
+    // differently, and that is correct.
+    const isTTY = Boolean((this.#stream as { isTTY?: boolean }).isTTY);
+    const encoding = options.encoding ?? "auto";
+    this.#pretty = encoding === "pretty" || (encoding === "auto" && isTTY);
+    this.#color = this.#pretty
+      ? decideColor({ setting: options.color ?? "auto", env: options.env, isTTY })
+      : false;
+    this.#encodeBytes = options.encodeBytes;
+  }
+
+  write(record: LogRecord): void {
+    this.#stream.write(
+      this.#pretty
+        ? encodePrettyLine(record, { color: this.#color })
+        : encodeJsonLine(record, { encodeBytes: this.#encodeBytes }),
+    );
+  }
+
+  async flush(): Promise<void> {
+    // Nothing is held: every record is handed to the descriptor on write.
+  }
+
+  flushSync(): void {
+    // Same — the write already reached the OS.
+  }
+
+  async close(): Promise<void> {
+    // The process owns stdout/stderr; a sink never closes them.
+  }
+}

package/src/logging/debug-wire-sink.ts

@@ -0,0 +1,85 @@
+import type { LogRecord } from "@telorun/sdk";
+import { toJsonProfile, type BytesEncoder } from "./encode-json.js";
+import type { LogSinkInstance } from "./log-sink.js";
+
+/**
+ * The `debug-wire` sink — `kernel/specs/logging.md` §10.2 and §11.4.
+ *
+ * **Not declarable.** It is host-attached when a debug consumer connects
+ * (`--debug` / `--inspect`) and detached on disconnect, which makes it tooling
+ * attachment rather than application configuration — the same category as TTY
+ * detection, not a violation of D6.
+ *
+ * Not sync-flushable: delivery crosses an SSE/stream boundary owned by the host,
+ * so a `fatal` record's flush here is initiated but never awaited (§10.5).
+ */
+
+export const DEBUG_WIRE_SINK_ID = "<debug-wire>";
+
+export class DebugWireSink implements LogSinkInstance {
+  readonly sinkId = DEBUG_WIRE_SINK_ID;
+  readonly level: number;
+  readonly syncFlushable = false;
+
+  readonly #emit: (frame: { kind: "record"; timestamp: string; record: Record<string, unknown> }) => void;
+  readonly #encodeBytes: BytesEncoder | undefined;
+
+  constructor(options: {
+    level: number;
+    /** Hands a §11.4 `record` frame to the host's wire writer. */
+    emit: (frame: { kind: "record"; timestamp: string; record: Record<string, unknown> }) => void;
+    /** Offloads `bytes` attributes to the host's blob store when it has one —
+     *  the debug wire does. Raw bytes are never inlined (§6.1). */
+    encodeBytes?: BytesEncoder;
+  }) {
+    this.level = options.level;
+    this.#emit = options.emit;
+    this.#encodeBytes = options.encodeBytes;
+  }
+
+  write(record: LogRecord): void {
+    const profile = toJsonProfile(record);
+    if (this.#encodeBytes) offloadBytes(profile, this.#encodeBytes);
+    this.#emit({
+      kind: "record",
+      timestamp: new Date(Number(record.timestamp / 1_000_000n)).toISOString(),
+      record: profile,
+    });
+  }
+
+  async flush(): Promise<void> {
+    // Frames are handed to the host synchronously; the host owns delivery.
+  }
+
+  flushSync(): void {
+    // Never synchronously drainable — see the class doc.
+  }
+
+  async close(): Promise<void> {}
+}
+
+/** Replace `Uint8Array` leaves with the host's pointer form, bounded by the
+ *  attribute limits already applied upstream. */
+function offloadBytes(value: unknown, encodeBytes: BytesEncoder): void {
+  const stack: unknown[] = [value];
+  let guard = 0;
+  while (stack.length > 0 && guard < 10_000) {
+    guard += 1;
+    const current = stack.pop();
+    if (!current || typeof current !== "object") continue;
+    if (Array.isArray(current)) {
+      for (let i = 0; i < current.length; i += 1) {
+        const item = current[i];
+        if (item instanceof Uint8Array) current[i] = encodeBytes(item);
+        else stack.push(item);
+      }
+      continue;
+    }
+    const record = current as Record<string, unknown>;
+    for (const key of Object.keys(record)) {
+      const item = record[key];
+      if (item instanceof Uint8Array) record[key] = encodeBytes(item);
+      else stack.push(item);
+    }
+  }
+}

package/src/logging/drop-accounting.ts

@@ -0,0 +1,108 @@
+import type { DropCause } from "./log-sink.js";
+
+/**
+ * Drop accounting — `kernel/specs/logging.md` §10.4.
+ *
+ * A runtime maintains a monotonic counter of records dropped per sink, per
+ * cause. When drops occur and then cease, it emits exactly one `warn` record
+ * reporting the count and the cause. **Dropping without accounting is
+ * non-conformant** — "nothing is silently lost" is a design principle, not a
+ * nice-to-have, so every drop, truncation, and sink failure is counted and
+ * surfaced.
+ */
+
+/** Sampling drops happen before fan-out, so they are not attributable to any one
+ *  sink and are counted against the pipeline itself. */
+export const PIPELINE_SINK_ID = "<pipeline>";
+
+/** How long a cause must go quiet before its recovery warning is emitted. */
+const QUIESCE_MS = 1000;
+
+interface Counter {
+  /** Monotonic across the process lifetime; never reset. */
+  total: number;
+  /** Total as of the last emitted recovery warning. */
+  reported: number;
+  timer: ReturnType<typeof setTimeout> | undefined;
+}
+
+export interface DropReport {
+  sinkId: string;
+  cause: DropCause;
+  /** Records dropped since the previous report. */
+  count: number;
+  /** Monotonic lifetime total for this (sink, cause) pair. */
+  total: number;
+}
+
+export class DropRegistry {
+  readonly #counters = new Map<string, Counter>();
+  readonly #onRecovered: (report: DropReport) => void;
+  /** Guards against a recovery warning that itself drops, which would otherwise
+   *  re-arm the timer forever. */
+  #reporting = false;
+
+  constructor(onRecovered: (report: DropReport) => void) {
+    this.#onRecovered = onRecovered;
+  }
+
+  record(sinkId: string, cause: DropCause, count = 1): void {
+    const key = `${sinkId}\x00${cause}`;
+    let counter = this.#counters.get(key);
+    if (!counter) {
+      counter = { total: 0, reported: 0, timer: undefined };
+      this.#counters.set(key, counter);
+    }
+    // Always count — a drop caused by emitting the recovery warning itself is
+    // still a drop, and undercounting it is exactly the silent loss this class
+    // exists to prevent.
+    counter.total += count;
+
+    // The only thing suppressed while a recovery warning is in flight is the
+    // timer re-arm: re-arming here would loop forever (the warning's own drop
+    // re-arms the timer, which fires and drops again). The increment above keeps
+    // the total honest; the next ordinary drop — or `reportPending` at
+    // shutdown — surfaces it, since `total !== reported`.
+    if (this.#reporting) return;
+
+    if (counter.timer) clearTimeout(counter.timer);
+    counter.timer = setTimeout(() => this.#report(sinkId, cause, counter!), QUIESCE_MS);
+    // A pending drop report must never be the reason a process stays alive.
+    (counter.timer as { unref?: () => void }).unref?.();
+  }
+
+  /** Lifetime total for a (sink, cause) pair. */
+  total(sinkId: string, cause: DropCause): number {
+    return this.#counters.get(`${sinkId}\x00${cause}`)?.total ?? 0;
+  }
+
+  /** Emit any outstanding reports immediately — used at shutdown so a run that
+   *  ends while still dropping does not lose its final accounting. */
+  reportPending(): void {
+    for (const [key, counter] of this.#counters) {
+      if (counter.total === counter.reported) continue;
+      const [sinkId, cause] = key.split("\x00") as [string, DropCause];
+      this.#report(sinkId, cause, counter);
+    }
+  }
+
+  dispose(): void {
+    for (const counter of this.#counters.values()) {
+      if (counter.timer) clearTimeout(counter.timer);
+      counter.timer = undefined;
+    }
+  }
+
+  #report(sinkId: string, cause: DropCause, counter: Counter): void {
+    counter.timer = undefined;
+    const count = counter.total - counter.reported;
+    if (count <= 0) return;
+    counter.reported = counter.total;
+    this.#reporting = true;
+    try {
+      this.#onRecovered({ sinkId, cause, count, total: counter.total });
+    } finally {
+      this.#reporting = false;
+    }
+  }
+}

package/src/logging/encode-json.ts

@@ -0,0 +1,98 @@
+import { formatUnixNano, type AnyValue, type ErrorValue, type LogRecord } from "@telorun/sdk";
+
+/**
+ * The `json` encoding — `kernel/specs/logging.md` §11.1. One JSON object per
+ * line, UTF-8, newline-terminated.
+ *
+ * No de-facto cross-ecosystem standard exists for key names, so Telo defines its
+ * own profile and keeps OTLP as a separate one. Keys are emitted in the §11.1
+ * order for diffability, and extension data belongs in `attributes` — unknown
+ * top-level keys are never emitted.
+ */
+
+/** How a `bytes` attribute is rendered. Raw bytes are never inlined into a text
+ *  encoding: a sink with a blob store offloads them to a pointer, and every
+ *  other sink base64-encodes (§6.1). */
+export type BytesEncoder = (bytes: Uint8Array) => AnyValue;
+
+export const base64Bytes: BytesEncoder = (bytes) => Buffer.from(bytes).toString("base64");
+
+export interface JsonEncodeOptions {
+  encodeBytes?: BytesEncoder;
+}
+
+/** Encode one record as a newline-terminated JSON line. */
+export function encodeJsonLine(record: LogRecord, options: JsonEncodeOptions = {}): string {
+  return `${encodeJson(record, options)}\n`;
+}
+
+/** Encode one record as a JSON object, without the trailing newline — the shape
+ *  the debug wire nests inside its `record` frame (§11.4). */
+export function encodeJson(record: LogRecord, options: JsonEncodeOptions = {}): string {
+  return JSON.stringify(toJsonProfile(record), makeReplacer(options.encodeBytes ?? base64Bytes));
+}
+
+/** The §11.1 key profile as a plain object, in the recommended order. Exposed
+ *  separately because the debug wire embeds the same profile rather than
+ *  re-deriving it. */
+export function toJsonProfile(record: LogRecord): Record<string, unknown> {
+  const out: Record<string, unknown> = {
+    time: formatUnixNano(record.timestamp),
+    level: record.severityText.toUpperCase(),
+    severity: record.severityNumber,
+    msg: record.message,
+  };
+
+  // `observed_timestamp` is deliberately NOT emitted: §11.1 defines a closed key
+  // set and forbids extra top-level keys, and §17's schema is
+  // `additionalProperties: false`. The field survives on the record model and in
+  // the `otlp` profile, which has a real `observedTimeUnixNano` slot for it.
+  if (record.traceId !== undefined) out["trace_id"] = record.traceId;
+  if (record.spanId !== undefined) out["span_id"] = record.spanId;
+  if (record.traceFlags !== undefined) out["trace_flags"] = record.traceFlags;
+  if (record.resource !== undefined) out["resource"] = record.resource;
+  if (record.module !== undefined) out["module"] = record.module;
+  if (record.scope !== undefined) out["scope"] = record.scope;
+  // Nested, never flattened — flattening risks collision with reserved keys.
+  // Emitted with keys in sorted (code-point) order so the `json` encoding is
+  // byte-identical across runtimes (§16 vector 18): attribute keys are arbitrary
+  // user data with no natural order, and sorted is the only order both this
+  // runtime and a Rust `BTreeMap`-backed one produce without extra config.
+  if (record.attributes !== undefined) out["attributes"] = sortKeysDeep(record.attributes);
+  if (record.error !== undefined) out["err"] = record.error satisfies ErrorValue;
+  if (record.eventName !== undefined) out["event_name"] = record.eventName;
+  if (record.droppedAttributesCount) {
+    out["dropped_attributes_count"] = record.droppedAttributesCount;
+  }
+
+  return out;
+}
+
+/** Rebuild an attribute value with every nested object's keys in sorted order.
+ *  `JSON.stringify` emits string keys in insertion order, so reconstructing the
+ *  object with sorted insertion is what pins the byte order. Arrays keep their
+ *  index order; `Uint8Array` is a leaf. The attributes are already normalized
+ *  (§6.3), so depth and breadth are bounded and this cannot diverge. */
+function sortKeysDeep(value: AnyValue): AnyValue {
+  if (value === null || typeof value !== "object") return value;
+  if (value instanceof Uint8Array) return value;
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  const sorted: Record<string, AnyValue> = {};
+  for (const key of Object.keys(value).sort()) sorted[key] = sortKeysDeep(value[key]!);
+  return sorted;
+}
+
+function makeReplacer(encodeBytes: BytesEncoder) {
+  return function replacer(this: unknown, _key: string, value: unknown): unknown {
+    if (typeof value === "bigint") {
+      // Values beyond 2^53 lose precision in a JS receiver, so they degrade to a
+      // decimal string rather than to a wrong number — the same reasoning OTLP
+      // gives for quoting its 64-bit fields.
+      return value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)
+        ? Number(value)
+        : value.toString();
+    }
+    if (value instanceof Uint8Array) return encodeBytes(value);
+    return value;
+  };
+}