@telorun/kernel 0.48.0 → 0.50.0

package/src/logging/encode-pretty.ts

@@ -0,0 +1,117 @@
+import { severityFloor, type AnyValue, type ErrorValue, type LogRecord } from "@telorun/sdk";
+
+/**
+ * The `pretty` encoding — `kernel/specs/logging.md` §11.2. For humans on a
+ * terminal:
+ *
+ *     12:34:56.789 INFO  Http.Server.api  listening  net.host.port=8080
+ *
+ * The color table is a modal synthesis across pino-pretty, zap, tint,
+ * tracing-subscriber, consola, and winston, which do not fully agree — zap alone
+ * uses magenta for DEBUG and blue for INFO, and TRACE has no consensus. It is a
+ * deliberate choice, not a standard.
+ */
+
+const RESET = "\u001b[0m";
+
+const LEVEL_COLOR: Readonly<Record<number, string>> = {
+  1: "\u001b[2m", // TRACE — dim
+  5: "\u001b[34m", // DEBUG — blue
+  9: "\u001b[32m", // INFO — green
+  13: "\u001b[33m", // WARN — yellow
+  17: "\u001b[31m", // ERROR — red
+  21: "\u001b[1;41m", // FATAL — bold, red background
+};
+
+const DIM = "\u001b[2m";
+
+export interface PrettyEncodeOptions {
+  color: boolean;
+}
+
+export function encodePrettyLine(record: LogRecord, options: PrettyEncodeOptions): string {
+  return `${encodePretty(record, options)}\n`;
+}
+
+export function encodePretty(record: LogRecord, options: PrettyEncodeOptions): string {
+  const paint = options.color
+    ? (code: string, text: string) => `${code}${text}${RESET}`
+    : (_code: string, text: string) => text;
+
+  const parts: string[] = [
+    formatLocalTime(record.timestamp),
+    paint(LEVEL_COLOR[severityFloor(record.severityNumber)]!, record.severityText.padEnd(5)),
+  ];
+
+  if (record.resource) parts.push(`${record.resource.kind}.${record.resource.name}`);
+
+  // The message itself is never colored by level — only the level token is.
+  parts.push(record.message);
+
+  const attributes = record.attributes;
+  if (attributes) {
+    for (const [key, value] of Object.entries(attributes)) {
+      parts.push(`${paint(DIM, key)}=${formatAttributeValue(value)}`);
+    }
+  }
+
+  if (record.droppedAttributesCount) {
+    parts.push(`${paint(DIM, "dropped_attributes_count")}=${record.droppedAttributesCount}`);
+  }
+
+  let line = parts.join("  ");
+
+  if (record.error) line += `\n${formatError(record.error, paint)}`;
+
+  return line;
+}
+
+/** `HH:MM:ss.SSS`, local timezone. Millisecond resolution: the sub-millisecond
+ *  digits of the record's nanosecond timestamp are noise on a console line. */
+function formatLocalTime(timestamp: bigint): string {
+  const date = new Date(Number(timestamp / 1_000_000n));
+  const hh = String(date.getHours()).padStart(2, "0");
+  const mm = String(date.getMinutes()).padStart(2, "0");
+  const ss = String(date.getSeconds()).padStart(2, "0");
+  const ms = String(date.getMilliseconds()).padStart(3, "0");
+  return `${hh}:${mm}:${ss}.${ms}`;
+}
+
+function formatAttributeValue(value: AnyValue): string {
+  if (value === null) return "null";
+  if (value instanceof Uint8Array) return `<${value.byteLength} bytes>`;
+  if (typeof value === "object") return quoteIfNeeded(JSON.stringify(value, jsonSafe));
+  return quoteIfNeeded(String(value));
+}
+
+/** Values containing whitespace, `"`, or `=` must be quoted so the `key=value`
+ *  stream stays unambiguously parseable by eye. */
+function quoteIfNeeded(text: string): string {
+  return /[\s"=]/.test(text) ? JSON.stringify(text) : text;
+}
+
+function jsonSafe(_key: string, value: unknown): unknown {
+  if (typeof value === "bigint") return value.toString();
+  if (value instanceof Uint8Array) return `<${value.byteLength} bytes>`;
+  return value;
+}
+
+/** Errors render after the message; the stack goes on following lines,
+ *  indented, unmodified. The `cause` chain follows, already bounded by §6.3. */
+function formatError(error: ErrorValue, paint: (code: string, text: string) => string): string {
+  const lines: string[] = [`  ${paint(LEVEL_COLOR[17]!, error.type)}: ${error.message}`];
+  if (error.stack) {
+    for (const line of error.stack.split("\n")) lines.push(`    ${line}`);
+  }
+  let cause = error.cause;
+  let guard = 0;
+  while (cause && guard < 16) {
+    lines.push(`  ${paint(DIM, "caused by")} ${cause.type}: ${cause.message}`);
+    if (cause.stack) {
+      for (const line of cause.stack.split("\n")) lines.push(`    ${line}`);
+    }
+    cause = cause.cause;
+    guard += 1;
+  }
+  return lines.join("\n");
+}

package/src/logging/file-sink.ts

@@ -0,0 +1,87 @@
+import { closeSync, openSync, writeSync } from "node:fs";
+import type { LogRecord } from "@telorun/sdk";
+import { encodeJsonLine, type BytesEncoder } from "./encode-json.js";
+import { encodePrettyLine } from "./encode-pretty.js";
+import { DEFAULT_BUFFER_POLICY, type LogSinkInstance, type SinkBufferPolicy } from "./log-sink.js";
+import { RecordBuffer } from "./record-buffer.js";
+
+/**
+ * `Telo.FileSink` — a kernel built-in (§10.2). Asynchronous, `json` by default.
+ *
+ * Sync-flushable: a positional write is available on every target platform, so a
+ * `fatal` record is durable by the time `log()` returns. That is what makes the
+ * file sink a legitimate audit destination while an OTLP sink is not — delivery
+ * there is a network round-trip that cannot complete without yielding.
+ */
+
+export type FileEncoding = "json" | "pretty";
+
+export interface FileSinkOptions {
+  sinkId: string;
+  level: number;
+  destination: string;
+  encoding?: FileEncoding;
+  policy?: SinkBufferPolicy;
+  onDrop: () => void;
+  encodeBytes?: BytesEncoder;
+}
+
+export class FileSink implements LogSinkInstance {
+  readonly sinkId: string;
+  readonly level: number;
+  readonly syncFlushable = true;
+
+  readonly #buffer: RecordBuffer;
+  readonly #encode: (record: LogRecord) => string;
+  readonly #fd: number;
+  #timer: ReturnType<typeof setInterval> | undefined;
+  #closed = false;
+
+  constructor(options: FileSinkOptions) {
+    this.sinkId = options.sinkId;
+    this.level = options.level;
+    const policy = options.policy ?? DEFAULT_BUFFER_POLICY;
+    this.#buffer = new RecordBuffer(policy, options.onDrop);
+    const encoding = options.encoding ?? "json";
+    this.#encode =
+      encoding === "pretty"
+        ? (record) => encodePrettyLine(record, { color: false })
+        : (record) => encodeJsonLine(record, { encodeBytes: options.encodeBytes });
+
+    this.#fd = openSync(options.destination, "a");
+
+    this.#timer = setInterval(() => this.flushSync(), policy.flushIntervalMs);
+    // A pending flush tick must never be the reason a process stays alive; the
+    // shutdown flush is what guarantees the tail is written.
+    (this.#timer as { unref?: () => void }).unref?.();
+  }
+
+  write(record: LogRecord): void {
+    if (this.#closed) return;
+    this.#buffer.push(record);
+  }
+
+  async flush(): Promise<void> {
+    this.flushSync();
+  }
+
+  flushSync(): void {
+    if (this.#closed) return;
+    const records = this.#buffer.drain();
+    if (records.length === 0) return;
+    let payload = "";
+    for (const record of records) payload += this.#encode(record);
+    writeSync(this.#fd, payload);
+  }
+
+  async close(): Promise<void> {
+    if (this.#closed) return;
+    this.flushSync();
+    this.#closed = true;
+    if (this.#timer) {
+      clearInterval(this.#timer);
+      this.#timer = undefined;
+    }
+    closeSync(this.#fd);
+  }
+}

package/src/logging/index.ts

@@ -0,0 +1,65 @@
+/**
+ * Structured logging — the Node.js implementation of `kernel/specs/logging.md`.
+ *
+ * The record model, severity scale, and `Logger` surface live in `@telorun/sdk`
+ * because module authors consume them; everything here is the runtime half —
+ * the pipeline, the encodings, the sinks, and the policies that gate emission.
+ * The redaction path grammar lives in `@telorun/analyzer` so `telo check` and
+ * the runtime share one parser rather than two that can drift.
+ */
+
+export { BOOTSTRAP_SINK_ID, createBootstrapWriter } from "./bootstrap-writer.js";
+export { decideColor } from "./color-precedence.js";
+export type { ColorDecisionInput, ColorSetting } from "./color-precedence.js";
+export { ConsoleSink } from "./console-sink.js";
+export { DEBUG_WIRE_SINK_ID, DebugWireSink } from "./debug-wire-sink.js";
+export type { ConsoleDestination, ConsoleEncoding, ConsoleSinkOptions } from "./console-sink.js";
+export { DropRegistry, PIPELINE_SINK_ID } from "./drop-accounting.js";
+export type { DropReport } from "./drop-accounting.js";
+export { base64Bytes, encodeJson, encodeJsonLine, toJsonProfile } from "./encode-json.js";
+export type { BytesEncoder, JsonEncodeOptions } from "./encode-json.js";
+export { encodePretty, encodePrettyLine } from "./encode-pretty.js";
+export type { PrettyEncodeOptions } from "./encode-pretty.js";
+export { FileSink } from "./file-sink.js";
+export type { FileEncoding, FileSinkOptions } from "./file-sink.js";
+export {
+  BLOCK_UNSUPPORTED,
+  blockUnsupportedMessage,
+  DEFAULT_BUFFER_POLICY,
+} from "./log-sink.js";
+export type { DropCause, LogSinkInstance, OnFull, SinkBufferPolicy } from "./log-sink.js";
+export { LoggingPipeline, ROOT_SCOPE_CONFIG } from "./logging-pipeline.js";
+export type { PipelineOptions, ScopeConfig, TraceContextProvider } from "./logging-pipeline.js";
+export {
+  DEFAULT_ATTRIBUTE_LIMITS,
+  normalizeAttributes,
+} from "./normalize-attributes.js";
+export type { AttributeLimits, NormalizedAttributes, NormalizeOptions } from "./normalize-attributes.js";
+export {
+  compileRedactionPolicy,
+  DEFAULT_CENSOR,
+  EMPTY_REDACTION_POLICY,
+  redactAttributes,
+  redactError,
+} from "./redact-attributes.js";
+export type { CompiledRedactionPath, RedactionPolicy } from "./redact-attributes.js";
+export { RecordBuffer } from "./record-buffer.js";
+export { Sampler } from "./sampler.js";
+export type { SamplingConfig } from "./sampler.js";
+export {
+  formatSpanCounter,
+  formatSpanId,
+  newTraceId,
+  normalizeSpanId,
+  normalizeTraceId,
+  saltSpanId,
+} from "./span-id.js";
+export { toErrorValue } from "./to-error-value.js";
+export {
+  formatTraceParent,
+  parseTraceParent,
+  parseTraceState,
+  TRACE_FLAG_RANDOM,
+  TRACE_FLAG_SAMPLED,
+} from "./trace-parent.js";
+export type { TraceContext } from "./trace-parent.js";

package/src/logging/kernel-logging.ts

@@ -0,0 +1,266 @@
+import {
+  parseLevelName,
+  SEVERITY,
+  type LevelName,
+  type LogAttributes,
+  type Logger,
+  type ResourceRef,
+} from "@telorun/sdk";
+import { BOOTSTRAP_SINK_ID, createBootstrapWriter } from "./bootstrap-writer.js";
+import { ConsoleSink } from "./console-sink.js";
+import { compileRedactionPolicy, EMPTY_REDACTION_POLICY } from "./redact-attributes.js";
+import type { DropCause, LogSinkInstance } from "./log-sink.js";
+import { createLoggingHost, type LoggingHost } from "./logging-host.js";
+import { LoggingPipeline, type ScopeConfig, type TraceContextProvider } from "./logging-pipeline.js";
+import type { SamplingConfig } from "./sampler.js";
+
+/**
+ * The kernel's ownership of the logging pipeline — `kernel/specs/logging.md`
+ * §12.
+ *
+ * Sequencing is the whole job here. An internal console writer covers process
+ * start through manifest validation, because declared sinks cannot instantiate
+ * before the block that declares them has been validated. Once the manifest
+ * resolves, the declared configuration takes over: eager sinks attach, buffered
+ * records replay, and the bootstrap writer steps aside.
+ */
+
+/** The raw `logging:` block as authored, after CEL evaluation. */
+export interface LoggingManifestBlock {
+  level?: string;
+  attributes?: LogAttributes;
+  redact?: { paths?: string[]; censor?: string; remove?: boolean };
+  sampling?: { first?: number; thereafter?: number; tick?: string; sampleErrors?: boolean };
+  sinks?: unknown[];
+}
+
+const DEFAULT_SAMPLING_TICK_MS = 1000;
+
+/** The module-context tree as far as logging is concerned — just enough to walk
+ *  children and read each one's resolved scope config, declared structurally so
+ *  this file stays independent of the concrete `ModuleContext`. */
+export interface LoggingContextNode {
+  readonly children?: readonly LoggingContextNode[];
+  getLoggingConfig?(): ScopeConfig | undefined;
+}
+
+/** How many sinks the root Application declared. Zero means the runtime behaves
+ *  exactly as if a single `Telo.ConsoleSink` were declared (§12.1), which is why
+ *  the bootstrap writer is replaced by a threshold-aware one rather than left as
+ *  the fixed-`info` writer. */
+function declaredSinkCount(manifests: readonly { kind?: string }[]): number {
+  const root = manifests.find((m) => m.kind === "Telo.Application") as
+    | { logging?: { sinks?: unknown[] } }
+    | undefined;
+  return root?.logging?.sinks?.length ?? 0;
+}
+
+export class KernelLogging {
+  readonly pipeline: LoggingPipeline;
+  readonly host: LoggingHost;
+
+  #rootScope: ScopeConfig;
+  #bootstrap: LogSinkInstance | undefined;
+  #sealed = false;
+  /** Kept so the zero-config console sink can be rebuilt at the resolved
+   *  threshold once the manifest is known (see {@link sealBootstrap}). */
+  readonly #streams: {
+    env: Record<string, string | undefined>;
+    stdout: NodeJS.WritableStream;
+    stderr: NodeJS.WritableStream;
+  };
+
+  constructor(options: {
+    env: Record<string, string | undefined>;
+    stdout: NodeJS.WritableStream;
+    stderr: NodeJS.WritableStream;
+    /** The process's real stderr — §8.4's fallback diagnostic stream. Kept
+     *  distinct from the kernel's injectable `stderr` so a captured stream can
+     *  never swallow the report that the capture itself failed. */
+    fallbackStream?: { write(chunk: string): unknown };
+  }) {
+    this.#streams = { env: options.env, stdout: options.stdout, stderr: options.stderr };
+    this.pipeline = new LoggingPipeline({
+      fallbackStream: options.fallbackStream ?? {
+        write: (chunk: string) => process.stderr.write(chunk),
+      },
+    });
+
+    // §12.3: a fixed default of `info` until the manifest resolves. This phase
+    // is the only one not manifest-governed, and it is deliberately not
+    // configurable by any other means.
+    this.#rootScope = {
+      threshold: SEVERITY.info,
+      redaction: EMPTY_REDACTION_POLICY,
+    };
+
+    this.#bootstrap = createBootstrapWriter(options);
+    this.pipeline.attach(this.#bootstrap);
+
+    this.host = createLoggingHost(
+      this.pipeline,
+      () => this.#rootScope.threshold,
+      (sinkId: string, cause: DropCause, count?: number) => this.recordDrop(sinkId, cause, count),
+    );
+  }
+
+  get rootScope(): ScopeConfig {
+    return this.#rootScope;
+  }
+
+  setTraceContextProvider(provider: TraceContextProvider | undefined): void {
+    this.pipeline.setTraceContextProvider(provider);
+  }
+
+  recordDrop(sinkId: string, cause: DropCause, count = 1): void {
+    // Routed through the pipeline so the recovery warning §10.4 requires is
+    // emitted as an ordinary record and reaches every sink.
+    this.pipeline.recordDrop(sinkId, cause, count);
+  }
+
+  /**
+   * Adopt the manifest's declared configuration. Called as soon as the
+   * `logging:` block has been validated — after that point the bootstrap default
+   * is no longer in force.
+   */
+  applyRootConfig(block: LoggingManifestBlock | undefined, secretValues?: ReadonlySet<string>): void {
+    this.#rootScope = buildScopeConfig(block, {
+      threshold: SEVERITY.info,
+      redaction: EMPTY_REDACTION_POLICY,
+      secretValues,
+    });
+  }
+
+  /**
+   * Detach the bootstrap writer and stop holding records for replay. Called once
+   * every declared sink has attached: the buffer exists to cover the pre-attach
+   * window, and a consumer connecting later (the debug wire) wants the live
+   * stream rather than the whole process history.
+   *
+   * When the manifest declares no sinks at all, the runtime behaves exactly as
+   * if a single `Telo.ConsoleSink` were declared — "pretty logs on stderr in a
+   * terminal, JSON when piped", with no imports.
+   *
+   * That equivalence is why the bootstrap writer is *replaced* here rather than
+   * promoted in place. The bootstrap writer is pinned at `info` (§12.3), but a
+   * declared `Telo.ConsoleSink` with no explicit `level:` takes the resolved
+   * scope threshold — so promoting the fixed-`info` writer would silently ignore
+   * a root `logging.level`, in both directions (a `debug` never lowers the gate,
+   * a `warn` never raises it). The fresh sink is built at the resolved threshold,
+   * so `logging: { level: debug }` with no `sinks:` behaves as documented.
+   */
+  sealBootstrap(manifests: readonly { kind?: string }[]): void {
+    if (this.#sealed) return;
+    this.#sealed = true;
+
+    if (this.#bootstrap) {
+      this.pipeline.detach(this.#bootstrap);
+      this.#bootstrap = undefined;
+    }
+    // Drop the replay buffer *before* attaching the zero-config sink, so the
+    // records the bootstrap writer already wrote live are not replayed into it.
+    this.pipeline.sealBootstrap();
+
+    if (declaredSinkCount(manifests) === 0) {
+      this.pipeline.attach(
+        new ConsoleSink({
+          sinkId: BOOTSTRAP_SINK_ID,
+          level: this.#rootScope.threshold,
+          destination: "stderr",
+          encoding: "auto",
+          color: "auto",
+          env: this.#streams.env,
+          stdout: this.#streams.stdout,
+          stderr: this.#streams.stderr,
+        }),
+      );
+    }
+  }
+
+  /** A logger scoped to a module context, stamped with a resource identity. */
+  createLogger(scope: ScopeConfig | undefined, resource?: ResourceRef): Logger {
+    return this.pipeline.createLogger(scope ?? this.#rootScope, resource);
+  }
+
+  /**
+   * Every module context's resolved logging configuration, keyed by its dotted
+   * import-alias path (`Api.Domain.Db`); the root is keyed `""`.
+   *
+   * This closes §12.2's loop between reading and configuring: the `scope` on a
+   * log line is exactly the path you write in the manifest to change that
+   * instance's level, and this answers "what level did that path actually
+   * resolve to" without re-deriving the cascade by hand. The tree walk is
+   * logging logic, so it lives here rather than on the orchestrator.
+   */
+  scopesFrom(rootContext: LoggingContextNode | undefined): Map<string, ScopeConfig> {
+    const scopes = new Map<string, ScopeConfig>();
+    scopes.set("", this.#rootScope);
+    const visit = (context: LoggingContextNode): void => {
+      for (const child of context.children ?? []) {
+        const config = child.getLoggingConfig?.();
+        if (config?.scope) scopes.set(config.scope, config);
+        visit(child);
+      }
+    };
+    if (rootContext) visit(rootContext);
+    return scopes;
+  }
+
+  /** The kernel's own logger — used for diagnostics the kernel emits about
+   *  itself, which §13.1 requires to go through this pipeline rather than to
+   *  `process.stderr` or `console.*`. */
+  kernelLogger(): Logger {
+    return this.pipeline.createLogger(this.#rootScope, undefined);
+  }
+
+  async shutdown(): Promise<void> {
+    await this.pipeline.close();
+  }
+}
+
+/**
+ * Merge a `logging:` block over an inherited configuration. Config cascades and
+ * may be narrowed at each hop, which is what makes a dependency you do not own
+ * diagnosable — raising `Api`'s level lifts everything beneath it without
+ * editing `Api`'s manifest (§12.2).
+ */
+export function buildScopeConfig(
+  block: LoggingManifestBlock | undefined,
+  inherited: ScopeConfig,
+): ScopeConfig {
+  if (!block) return inherited;
+
+  const level = block.level ? parseLevelName(block.level as LevelName) : undefined;
+
+  return {
+    threshold: level ?? inherited.threshold,
+    redaction: block.redact
+      ? compileRedactionPolicy({
+          paths: block.redact.paths,
+          censor: block.redact.censor,
+          remove: block.redact.remove,
+        })
+      : inherited.redaction,
+    sampling: block.sampling ? toSamplingConfig(block.sampling) : inherited.sampling,
+    secretValues: inherited.secretValues,
+    scope: inherited.scope,
+    module: inherited.module,
+    attributes: block.attributes ?? inherited.attributes,
+  };
+}
+
+function toSamplingConfig(sampling: NonNullable<LoggingManifestBlock["sampling"]>): SamplingConfig {
+  return {
+    first: sampling.first ?? 0,
+    thereafter: sampling.thereafter ?? 0,
+    tickMs: sampling.tick ? parseTickMs(sampling.tick) : DEFAULT_SAMPLING_TICK_MS,
+    sampleErrors: sampling.sampleErrors ?? false,
+  };
+}
+
+function parseTickMs(tick: string): number {
+  const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h)\s*$/.exec(tick);
+  if (!match) return DEFAULT_SAMPLING_TICK_MS;
+  const unit = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[match[2] as "ms" | "s" | "m" | "h"];
+  return Number(match[1]) * unit;
+}

package/src/logging/log-sink.ts

@@ -0,0 +1,18 @@
+/**
+ * The sink contract now lives in `@telorun/sdk` — §10.2 keeps the sink set open
+ * to the ecosystem, so a third-party sink module implements it as an ordinary
+ * module author rather than importing a kernel-internal type. Re-exported here
+ * so the kernel's own imports keep one spelling.
+ */
+export {
+  BLOCK_UNSUPPORTED,
+  blockUnsupportedMessage,
+  DEFAULT_BUFFER_POLICY,
+} from "@telorun/sdk";
+export type {
+  DropCause,
+  LoggingHost,
+  LogSinkInstance,
+  OnFull,
+  SinkBufferPolicy,
+} from "@telorun/sdk";

package/src/logging/logging-host.ts

@@ -0,0 +1,33 @@
+import { parseLevelName, type DropCause, type LevelName, type LoggingHost } from "@telorun/sdk";
+
+export type { LoggingHost } from "@telorun/sdk";
+import type { LoggingPipeline } from "./logging-pipeline.js";
+
+/**
+ * The narrow facade a sink controller sees — `kernel/specs/logging.md` §12.1.
+ *
+ * A sink is a resource, so its controller runs under an ordinary
+ * `ResourceContext`; this is the one extra surface it needs. It is deliberately
+ * small: attach, detach, resolve a level, count a drop. Everything else about
+ * the pipeline stays private to the kernel, so a third-party sink shipped as a
+ * module depends on this contract and nothing deeper.
+ */
+export function createLoggingHost(
+  pipeline: LoggingPipeline,
+  scopeThreshold: () => number,
+  recordDrop: (sinkId: string, cause: DropCause, count?: number) => void,
+): LoggingHost {
+  return {
+    attach: (sink) => pipeline.attach(sink),
+    detach: (sink) => pipeline.detach(sink),
+    levelFor: (level) => {
+      if (!level) return scopeThreshold();
+      const severity = parseLevelName(level as LevelName);
+      // The schema constrains `level:` to the six named levels, so an unknown
+      // value here means the manifest bypassed validation; fall back rather than
+      // throw, because a logging misconfiguration must not break boot.
+      return severity ?? scopeThreshold();
+    },
+    recordDrop,
+  };
+}