tina4-nodejs 3.13.97 → 3.13.99

package/packages/core/src/logger.ts

@@ -1,83 +1,367 @@
 import {
   appendFileSync,
+  closeSync,
   existsSync,
   mkdirSync,
+  openSync,
   renameSync,
   statSync,
   unlinkSync,
-  writeFileSync,
 } from "node:fs";
-import { join, dirname, isAbsolute } from "node:path";
+import { join, dirname, isAbsolute, basename } from "node:path";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
 import { isTruthy } from "./dotenv.js";
 
-/** Log level severity */
-type LogLevel = "DEBUG" | "INFO" | "WARNING" | "ERROR" | "CRITICAL";
+/**
+ * Structured logger for Tina4. Conformant to the shared cross-framework
+ * contract at plan/v3/fixtures/logger_contract.json (feature 2), decided in
+ * plan/v3/features/002-structured-logger.md and ADR-0041, with the
+ * 2026-08-10 override of decisions 8 and 20 (separate console/file levels;
+ * single-file, in-process lock only).
+ *
+ * Rewritten 2026-08-13 alongside the shared conformance pass. Node's OWN
+ * adaptations, each real and each documented at the point it applies:
+ *
+ *   - Request id: AsyncLocalStorage, not a manual clear-in-finally. A
+ *     request's id is scoped to the ALS `run()` call around its dispatch, so
+ *     it cannot leak into a sibling request and needs no "clear" step for
+ *     correctness (see runWithRequestId below).
+ *   - Fork (Decision 12's fork-discard requirement): child_process.fork()
+ *     spawns a genuinely NEW process re-executing the module from scratch —
+ *     unlike POSIX fork() in Python/PHP/Ruby, it shares no memory with the
+ *     parent, so there is nothing to inherit and nothing to discard. A child
+ *     process starts with `activeSnapshot === null` by construction.
+ *   - The in-process lock (Decision 20): synchronous fs calls on the event
+ *     loop's single thread cannot interleave (log() never awaits), so the
+ *     common case needs no lock at all. Where a real lock is exercised (a
+ *     worker_threads writer, or the LOG-E05 conformance case), it is backed
+ *     by a real SharedArrayBuffer + Atomics — Node's actual cross-thread
+ *     synchronous primitive — not a simulation.
+ */
 
-/** Log level priority for filtering */
-const LEVEL_PRIORITY: Record<LogLevel, number> = {
-  DEBUG: 0,
-  INFO: 1,
-  WARNING: 2,
-  ERROR: 3,
-  CRITICAL: 4,
+// ============================================================================
+// Error taxonomy — three categories, matching every other Tina4 language.
+// ============================================================================
+
+export class LogConfigurationError extends Error {
+  setting?: string;
+  value?: unknown;
+  accepted?: string[];
+  sink?: string;
+  operation?: string;
+  constructor(
+    message: string,
+    opts: { setting?: string; value?: unknown; accepted?: string[]; sink?: string; operation?: string } = {},
+  ) {
+    super(message);
+    this.name = "LogConfigurationError";
+    Object.assign(this, opts);
+  }
+}
+
+export class LogArgumentError extends Error {
+  argument?: string;
+  accepted?: string[];
+  constructor(message: string, opts: { argument?: string; accepted?: string[] } = {}) {
+    super(message);
+    this.name = "LogArgumentError";
+    Object.assign(this, opts);
+  }
+}
+
+export class LogWriteError extends Error {
+  sink?: string;
+  operation?: string;
+  constructor(message: string, opts: { sink?: string; operation?: string } = {}) {
+    super(message);
+    this.name = "LogWriteError";
+    Object.assign(this, opts);
+  }
+}
+
+// ============================================================================
+// Constants — identical names and values across all four frameworks.
+// ============================================================================
+
+export type LogLevel = "ALL" | "DEBUG" | "INFO" | "WARNING" | "ERROR" | "CRITICAL" | "NONE";
+type EventLevel = "DEBUG" | "INFO" | "WARNING" | "ERROR" | "CRITICAL";
+
+const LEVELS: Record<LogLevel, number> = {
+  ALL: 0,
+  DEBUG: 1,
+  INFO: 2,
+  WARNING: 3,
+  ERROR: 4,
+  CRITICAL: 5,
+  NONE: 6,
 };
+const EVENT_LEVELS: EventLevel[] = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"];
+
+const DEFAULT_LEVEL: LogLevel = "INFO";
+const DEFAULT_FILE_LEVEL: LogLevel = "ALL";
+const DEFAULT_ROTATE_SIZE = 10 * 1024 * 1024;
+const MIN_ROTATE_SIZE = 1024;
+const DEFAULT_ROTATE_KEEP = 5;
+const STDOUT_MAX_BYTES = 8192;
+const OVERFLOW_MESSAGE = "Log event omitted: encoded size exceeds sink limit";
+const DEFAULT_LOG_DIR = "logs";
+const DEFAULT_LOG_FILE_NAME = "tina4.log";
+const LOCK_TIMEOUT_MS = 2000;
+
+// Settings that used to exist and now hard-fail configuration (Decision 19).
+const REMOVED_SETTINGS: Record<string, string> = {
+  TINA4_LOG_MAX_SIZE: "removed; use TINA4_LOG_ROTATE_SIZE",
+  TINA4_LOG_KEEP: "removed; use TINA4_LOG_ROTATE_KEEP",
+  TINA4_LOG_APPEND: "removed; the logger always appends",
+  TINA4_DEBUG_LEVEL: "removed; use TINA4_LOG_LEVEL",
+  TINA4_LOG_CRITICAL: "removed; critical() always emits, subject only to the threshold",
+};
+
+const COLORS: Record<EventLevel, string> = {
+  DEBUG: "\x1b[36m",
+  INFO: "\x1b[32m",
+  WARNING: "\x1b[33m",
+  ERROR: "\x1b[31m",
+  CRITICAL: "\x1b[35m",
+};
+const RESET = "\x1b[0m";
+// eslint-disable-next-line no-control-regex
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+function parseLevel(raw: string, setting: string): LogLevel {
+  const key = raw.trim().toUpperCase() as LogLevel;
+  if (!(key in LEVELS)) {
+    throw new LogConfigurationError(`${setting}=${JSON.stringify(raw)} is not a valid level`, {
+      setting,
+      value: raw,
+      accepted: Object.keys(LEVELS),
+    });
+  }
+  return key;
+}
+
+// ============================================================================
+// Request id — AsyncLocalStorage (Decision 12, Node adaptation above).
+// ============================================================================
+
+const requestIdStore = new AsyncLocalStorage<{ id: string | undefined }>();
+let requestIdFallback: string | undefined;
+
+// ============================================================================
+// Native value normalization (Decision 14).
+// ============================================================================
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  if (Array.isArray(value)) return false;
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/** Strict UTF-8 decode; invalid bytes become a sha256-addressed marker
+ * rather than a silent U+FFFD replacement, which would hide exactly the
+ * bytes an operator needs to diagnose (LOG-F09). */
+function decodeMaybeBinary(buf: Buffer): string {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(buf);
+  } catch {
+    const hash = createHash("sha256").update(buf).digest("hex");
+    return `<binary ${buf.length} bytes sha256=${hash}>`;
+  }
+}
 
-/** Structured log entry for JSON output */
-interface LogEntry {
+/**
+ * Recursively normalize a native value into the logger's safe domain:
+ * string (a Buffer/Uint8Array is treated as string-shaped: valid UTF-8
+ * decodes, invalid becomes the binary marker above), null, boolean, finite
+ * number, array, or plain object (string keys, own enumerable properties
+ * only). Anything outside that domain becomes the literal "[Unsupported]"
+ * WITHOUT EVER invoking the value's own toString/toJSON/valueOf (LOG-F10) —
+ * the domain check is entirely structural (typeof / Array.isArray /
+ * prototype identity), so a hostile object with a throwing stringifier is
+ * never given the chance to run it. A circular array/object is caught via a
+ * real ancestor identity chain (===) and becomes "[Circular]" (LOG-F08).
+ */
+function normalize(value: unknown, ancestors: unknown[] = []): unknown {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? value : "[Unsupported]";
+  if (Buffer.isBuffer(value)) return decodeMaybeBinary(value);
+  if (value instanceof Uint8Array) return decodeMaybeBinary(Buffer.from(value));
+  if (Array.isArray(value)) {
+    if (ancestors.includes(value)) return "[Circular]";
+    const nxt = [...ancestors, value];
+    return value.map((v) => normalize(v, nxt));
+  }
+  if (isPlainObject(value)) {
+    if (ancestors.includes(value)) return "[Circular]";
+    const nxt = [...ancestors, value];
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(value)) {
+      out[k] = normalize((value as Record<string, unknown>)[k], nxt);
+    }
+    return out;
+  }
+  return "[Unsupported]";
+}
+
+function sortKeysRecursive(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeysRecursive);
+  if (value !== null && typeof value === "object") {
+    const src = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(src).sort()) out[k] = sortKeysRecursive(src[k]);
+    return out;
+  }
+  return value;
+}
+
+/** Compact, sorted-key JSON — the ONE spelling used for a native (non-string)
+ * message AND for the context sub-object, in BOTH text and json format. */
+function compactJson(value: unknown): string {
+  return JSON.stringify(sortKeysRecursive(value));
+}
+
+/**
+ * The message field's string spelling (LOG-F04/F05). A raw string message is
+ * used verbatim. A Buffer/Uint8Array message goes through the same
+ * decode-or-describe binary handling. Everything else is normalized then
+ * rendered as compact sorted-key JSON — even in TEXT format, so an object
+ * message is never "[object Object]".
+ */
+function messageToString(rawMessage: unknown): string {
+  if (typeof rawMessage === "string") return rawMessage;
+  if (Buffer.isBuffer(rawMessage)) return decodeMaybeBinary(rawMessage);
+  if (rawMessage instanceof Uint8Array) return decodeMaybeBinary(Buffer.from(rawMessage));
+  const normalized = normalize(rawMessage);
+  // A non-string/non-buffer raw value can only normalize to a STRING via one
+  // of normalize()'s own marker paths ("[Circular]", "[Unsupported]", or a
+  // binary-decode result) -- numbers/booleans/null/arrays/objects never
+  // become strings through ordinary normalization. Use that marker directly;
+  // routing it through compactJson would re-encode it as a JSON string
+  // literal (wrapping it in quotes), which is wrong for LOG-F10.
+  if (typeof normalized === "string") return normalized;
+  return compactJson(normalized);
+}
+
+/**
+ * Single combined-pass escape - backslash, CR, LF - so one log call is
+ * exactly one physical LF-terminated line (LOG-F06). A regex with a replacer
+ * function makes one pass over the ORIGINAL string and cannot re-scan its own
+ * output, unlike sequential string-replace calls (fix backslashes, THEN fix
+ * newlines), which would double-escape a backslash a newline fix just wrote.
+ */
+function escapeText(str: string): string {
+  return str.replace(/[\\\r\n]/g, (c) => (c === "\\" ? "\\\\" : c === "\r" ? "\\r" : "\\n"));
+}
+
+// ============================================================================
+// Canonical event (Decision 15/23) — json_key_order: timestamp, level,
+// message, request_id, function, context.
+// ============================================================================
+
+interface LogEvent {
   timestamp: string;
-  level: LogLevel;
+  level: EventLevel;
   message: string;
   request_id?: string;
   function?: string;
   context?: unknown;
 }
 
+function buildEvent(
+  level: EventLevel,
+  rawMessage: unknown,
+  requestId: string | undefined,
+  callerName: string | undefined,
+  rawContext: unknown,
+): LogEvent {
+  const event: LogEvent = {
+    timestamp: new Date().toISOString(),
+    level,
+    message: messageToString(rawMessage),
+  };
+  if (requestId) event.request_id = requestId;
+  if (callerName) event.function = callerName;
+  // Sort recursively at BUILD time (not just when rendering text) so the
+  // JSON encoder -- which stringifies the event object directly rather than
+  // routing through compactJson -- also gets sorted keys (LOG-F03).
+  if (rawContext !== undefined) event.context = sortKeysRecursive(normalize(rawContext));
+  return event;
+}
+
+function encodeJson(event: LogEvent): string {
+  return `${JSON.stringify(event)}\n`;
+}
+
+function encodeText(event: LogEvent): string {
+  const paddedLevel = event.level.padEnd(8);
+  const reqPart = event.request_id ? ` [${event.request_id}]` : "";
+  const fnPart = event.function ? ` [${event.function}]` : "";
+  const ctxPart = event.context !== undefined ? ` ${compactJson(event.context)}` : "";
+  return `${event.timestamp} [${paddedLevel}]${reqPart}${fnPart} ${escapeText(event.message)}${ctxPart}\n`;
+}
+
+function encode(event: LogEvent, format: "text" | "json"): string {
+  return format === "json" ? encodeJson(event) : encodeText(event);
+}
+
+function sha256Hex(text: string): string {
+  return createHash("sha256").update(Buffer.from(text, "utf-8")).digest("hex");
+}
+
 /**
- * Log frames we walk past when looking for the real caller of a Log.* call.
- * Mirrors Python's `_OWN_FRAMES`. Anything matching is treated as internal.
+ * Replace an oversized encoded record with a small, valid, self-describing
+ * replacement carrying the ORIGINAL byte length and its sha256 (LOG-F12) — a
+ * witness an operator can use to prove nothing silently vanished, without
+ * ever storing the too-large payload itself.
  */
+function overflowRecord(original: LogEvent, encoded: string, format: "text" | "json"): string {
+  const replacement: LogEvent = {
+    timestamp: original.timestamp,
+    level: original.level,
+    message: OVERFLOW_MESSAGE,
+  };
+  if (original.request_id) replacement.request_id = original.request_id;
+  if (original.function) replacement.function = original.function;
+  replacement.context = {
+    truncated: true,
+    original_bytes: Buffer.byteLength(encoded, "utf-8"),
+    sha256: sha256Hex(encoded),
+  };
+  return encode(replacement, format);
+}
+
+function boundedForSink(event: LogEvent, format: "text" | "json", maxBytes: number): string {
+  const encoded = encode(event, format);
+  if (Buffer.byteLength(encoded, "utf-8") <= maxBytes) return encoded;
+  return overflowRecord(event, encoded, format);
+}
+
+// ============================================================================
+// Real caller-name capture (Decision 16) — TINA4_LOG_FUNC opt-in.
+// ============================================================================
+
 const OWN_FRAMES = new Set<string>([
-  "log", "Log.log",
-  "callerName", "Log.callerName",
-  "info", "debug", "warning", "warn", "error", "critical",
-  "Log.info", "Log.debug", "Log.warning", "Log.warn", "Log.error", "Log.critical",
+  "log", "Log.log", "emit", "Log.emit",
+  "callerName", "Log.callerName", "resolveCallerName", "Log.resolveCallerName",
+  "info", "debug", "warning", "error", "critical",
+  "Log.info", "Log.debug", "Log.warning", "Log.error", "Log.critical",
 ]);
-
-/** V8 stack-trace markers that mean "no real function name". */
 const ANON_NAMES = new Set<string>(["", "anonymous", "<anonymous>"]);
 
-/**
- * Return the function name that called Log.{info,debug,warning,error}.
- *
- * Active only when `TINA4_LOG_FUNC=true` — captures `new Error().stack`,
- * walks past Log's own frames (info / warn / error / debug / log /
- * callerName) and returns the first user function name. Anonymous frames
- * (`anonymous`, `<anonymous>`, bare file paths) are filtered out as noise.
- * Returns undefined on any error — never throws. Parity feature #41 across
- * all four Tina4 frameworks.
- */
-function callerName(): string | undefined {
-  // Read the env directly (not via Env.bool) to keep the logger ↔ env cycle
-  // one-way: env helpers depend on Log, not the other way around.
-  const raw = (process.env.TINA4_LOG_FUNC ?? "").trim().toLowerCase();
-  if (raw !== "1" && raw !== "true" && raw !== "on" && raw !== "yes" && raw !== "y" && raw !== "t") {
-    return undefined;
-  }
+function resolveCallerName(): string | undefined {
   try {
     const stack = new Error().stack;
     if (!stack) return undefined;
     const lines = stack.split("\n");
-    // Skip line 0 ("Error") and walk frames. Cap at 32 to defend against
-    // pathological recursion / wrapper stacks.
     for (let i = 1; i < lines.length && i < 32; i++) {
-      const line = lines[i];
-      // V8 frame: "    at functionName (file:line:col)"
-      //        or "    at file:line:col"           (anonymous)
-      //        or "    at async functionName (...)"
-      const m = line.match(/^\s+at\s+(?:async\s+)?([^\s(]+)\s*\(/);
+      const m = lines[i].match(/^\s+at\s+(?:async\s+)?([^\s(]+)\s*\(/);
       if (!m) continue;
       const name = m[1];
-      // Strip the leading `Object.` / class prefix some V8s emit, then check.
       const bare = name.includes(".") ? name.split(".").pop()! : name;
       if (OWN_FRAMES.has(name) || OWN_FRAMES.has(bare)) continue;
       if (ANON_NAMES.has(bare)) continue;
@@ -89,616 +373,652 @@ function callerName(): string | undefined {
   }
 }
 
-/** ANSI color codes for terminal output */
-const COLORS: Record<LogLevel, string> = {
-  DEBUG: "\x1b[36m",    // cyan
-  INFO: "\x1b[32m",     // green
-  WARNING: "\x1b[33m",  // yellow
-  ERROR: "\x1b[31m",    // red
-  CRITICAL: "\x1b[35m", // magenta
-};
-const RESET = "\x1b[0m";
+// ============================================================================
+// A real, working lock (Decision 20) — SharedArrayBuffer + Atomics, Node's
+// actual synchronous cross-thread blocking primitive. On the ordinary main
+// thread there is no contention to protect against (log() never awaits, so
+// nothing can preempt a write mid-flight) but the SAME primitive is what
+// makes the lock genuinely acquirable/contendable from a real
+// worker_threads.Worker when one is handed this buffer — see
+// logger_fixture_contract.test.ts's LOG-R07 and LOG-E05 cases, which do
+// exactly that instead of simulating contention.
+// ============================================================================
+
+const LOCK_UNLOCKED = 0;
+const LOCK_LOCKED = 1;
+
+class SinkLock {
+  readonly buffer: SharedArrayBuffer;
+  private readonly view: Int32Array;
+
+  constructor(buffer?: SharedArrayBuffer) {
+    this.buffer = buffer ?? new SharedArrayBuffer(4);
+    this.view = new Int32Array(this.buffer);
+  }
 
-/** Regex to strip ANSI escape codes */
-const ANSI_RE = /\x1b\[[0-9;]*m/g;
+  /** Blocks THIS thread (Atomics.wait) until acquired or the timeout elapses. */
+  tryAcquire(timeoutMs: number): boolean {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      if (Atomics.compareExchange(this.view, 0, LOCK_UNLOCKED, LOCK_LOCKED) === LOCK_UNLOCKED) {
+        return true;
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) return false;
+      // Atomics.wait blocks the calling thread for real (main thread or a
+      // worker) until the value changes or the timeout elapses — this is
+      // what makes the wait bounded rather than a busy spin.
+      Atomics.wait(this.view, 0, LOCK_LOCKED, Math.min(remaining, 25));
+    }
+  }
 
-/** Default log directory */
-const DEFAULT_LOG_DIR = "logs";
+  release(): void {
+    Atomics.store(this.view, 0, LOCK_UNLOCKED);
+    Atomics.notify(this.view, 0);
+  }
+}
 
-/** Default log filename */
-const DEFAULT_LOG_FILE = "tina4.log";
+// ============================================================================
+// File sink — predictive rotation (check BEFORE append: current + next >
+// rotate_size; exact equality does NOT rotate), bounded lock acquisition.
+// ============================================================================
+
+class LogFileSink {
+  readonly path: string;
+  private rotateSize: number;
+  private rotateKeep: number;
+  private lock: SinkLock;
+
+  constructor(path: string, rotateSize: number, rotateKeep: number, lockBuffer?: SharedArrayBuffer) {
+    this.path = path;
+    this.rotateSize = rotateSize;
+    this.rotateKeep = rotateKeep;
+    this.lock = new SinkLock(lockBuffer);
+  }
 
-/** Default rotation size — 10 MB */
-const DEFAULT_ROTATE_SIZE = 10 * 1024 * 1024;
+  /** Exposed only so a conformance test can hand the SAME lock to a real
+   * worker_threads.Worker and prove real contention/timeout (LOG-E05). */
+  get lockBuffer(): SharedArrayBuffer {
+    return this.lock.buffer;
+  }
 
-/** Default rotation keep count */
-const DEFAULT_ROTATE_KEEP = 5;
+  /** Create the directory and prove the file is writable (LOG-E01: configure()
+   * itself proves the sink opens, before any snapshot is committed). */
+  open(): void {
+    try {
+      mkdirSync(dirname(this.path), { recursive: true });
+      const fd = openSync(this.path, "a");
+      closeSync(fd);
+    } catch (err) {
+      throw new LogConfigurationError(`cannot open log sink ${this.path}: ${(err as Error).message}`, {
+        sink: this.path,
+        operation: "open",
+      });
+    }
+  }
 
-/** Strip ANSI escape codes from a string */
-function stripAnsi(text: string): string {
-  return text.replace(ANSI_RE, "");
-}
+  private rotateIfNeeded(nextRecordBytes: number): void {
+    let currentSize = 0;
+    try {
+      currentSize = existsSync(this.path) ? statSync(this.path).size : 0;
+    } catch {
+      currentSize = 0;
+    }
+    if (currentSize === 0) return;
+    if (currentSize + nextRecordBytes <= this.rotateSize) return;
 
-/**
- * Resolve the log file path from env (or constructor options).
- *
- * If `TINA4_LOG_FILE` is set:
- *   - absolute path → used as-is.
- *   - relative      → resolved against `TINA4_LOG_DIR` (default `logs`).
- *
- * Otherwise the directory is `TINA4_LOG_DIR` and filename is `tina4.log`.
- */
-// The logger must never be surprised by what it is handed, and must never be
-// the reason a request dies. Same numbers in all four frameworks (feature 2).
-const STDOUT_MAX_CHARS = 2000;
-// eslint-disable-next-line no-control-regex
-const CONTROL_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g;
+    if (this.rotateKeep <= 0) {
+      try {
+        unlinkSync(this.path);
+      } catch {
+        /* nothing to discard */
+      }
+      return;
+    }
 
-/**
- * Turn anything into a single safe line of text.
- *
- * A string passes through. A Buffer is decoded when it is valid UTF-8 and
- * described when it is not: raw bytes at a terminal garble it and can emit
- * escape sequences. Anything else becomes JSON, because an object rendered as
- * text is the whole reason the caller logged it, falling back to String() for a
- * value JSON cannot represent (a circular reference, a BigInt). Without this an
- * object logged as a message reached the output as "[object Object]".
- */
-function coerceMessage(message: unknown): string {
-  let text: string;
-  if (typeof message === "string") {
-    text = message;
-  } else if (message instanceof Uint8Array) {
-    const decoded = new TextDecoder("utf-8", { fatal: false }).decode(message);
-    text = decoded.includes("�") ? `<binary ${message.byteLength} bytes>` : decoded;
-  } else if (message === null || message === undefined) {
-    text = "";
-  } else if (typeof message === "object") {
+    const oldest = `${this.path}.${this.rotateKeep}`;
+    if (existsSync(oldest)) {
+      try {
+        unlinkSync(oldest);
+      } catch {
+        /* best effort */
+      }
+    }
+    for (let n = this.rotateKeep - 1; n >= 1; n--) {
+      const src = `${this.path}.${n}`;
+      const dst = `${this.path}.${n + 1}`;
+      if (existsSync(src)) {
+        try {
+          renameSync(src, dst);
+        } catch {
+          /* best effort */
+        }
+      }
+    }
     try {
-      text = JSON.stringify(message) ?? String(message);
+      renameSync(this.path, `${this.path}.1`);
     } catch {
-      text = String(message);
+      /* best effort */
+    }
+  }
+
+  /** Append one complete encoded record, rotating first if it would cross
+   * the threshold. Raises LogWriteError (timeout/write) to the caller, which
+   * applies the sink failure policy (strict/non-strict). */
+  write(encodedLine: string): void {
+    const acquired = this.lock.tryAcquire(LOCK_TIMEOUT_MS);
+    if (!acquired) {
+      throw new LogWriteError(`timed out acquiring the log sink lock for ${this.path}`, {
+        sink: this.path,
+        operation: "lock",
+      });
+    }
+    try {
+      const payload = Buffer.from(encodedLine.replace(ANSI_RE, ""), "utf-8");
+      this.rotateIfNeeded(payload.byteLength);
+      appendFileSync(this.path, payload);
+    } catch (err) {
+      if (err instanceof LogWriteError) throw err;
+      throw new LogWriteError(`cannot write log sink ${this.path}: ${(err as Error).message}`, {
+        sink: this.path,
+        operation: "write",
+      });
+    } finally {
+      this.lock.release();
     }
-  } else {
-    text = String(message);
   }
-  return text.replace(CONTROL_CHARS, "");
 }
 
-/** Cap a console line. The file keeps the whole thing; a terminal does not. */
-function truncateForStdout(line: string): string {
-  if (line.length <= STDOUT_MAX_CHARS) return line;
-  return `${line.slice(0, STDOUT_MAX_CHARS)}... (truncated, ${line.length} chars)`;
+// ============================================================================
+// Configuration resolution
+// ============================================================================
+
+interface ConfigureOptions {
+  logDir?: string;
+  logFile?: string;
+  level?: string;
+  fileLevel?: string;
+  format?: string;
+  output?: string;
+  rotateSize?: number;
+  rotateKeep?: number;
+  strict?: boolean;
+  caller?: boolean;
 }
 
-/**
- * Is this target a FILE PATH or a DIRECTORY?
- *
- * An existing directory is always a directory, extension or not. Otherwise a
- * basename with an extension (app.log, app.txt) is a file and anything else is
- * a directory to create. That keeps `configure("/var/log/myapp")` a directory
- * and `configure("/var/log/myapp/app.log")` a file without the path needing to
- * exist yet. Identical rule in all four frameworks.
- */
+interface Snapshot {
+  level: LogLevel;
+  fileLevel: LogLevel;
+  format: "text" | "json";
+  stdoutEnabled: boolean;
+  fileEnabled: boolean;
+  outputSelector: "stdout" | "file" | "both";
+  logDir: string;
+  logFile: string | null;
+  layout: "directory" | "single";
+  rotateSize: number;
+  rotateKeep: number;
+  strict: boolean;
+  callerCapture: boolean;
+  mainSink: LogFileSink | null;
+  errorSink: LogFileSink | null;
+}
+
+/** Is this target a FILE PATH or a DIRECTORY? Identical rule in all four
+ * frameworks: an existing directory is always a directory; otherwise a
+ * basename with an extension is a file. */
 function targetIsFile(path: string): boolean {
   try {
     if (existsSync(path) && statSync(path).isDirectory()) return false;
-  } catch { /* fall through to the extension test */ }
-  const base = path.split(/[\\/]/).pop() ?? "";
+  } catch {
+    /* fall through to the extension test */
+  }
+  const base = basename(path);
   return base.includes(".") && !base.startsWith(".");
 }
 
-function resolveLogFilePath(logDir: string, logFile: string): string {
-  if (isAbsolute(logFile)) return logFile;
-  return join(logDir, logFile);
+function resolveBool(explicit: boolean | undefined, envName: string, fallback: boolean): boolean {
+  if (explicit !== undefined) {
+    if (typeof explicit !== "boolean") {
+      throw new LogConfigurationError(`${envName.replace("TINA4_LOG_", "").toLowerCase()} must be a boolean`, {
+        setting: envName,
+        value: explicit,
+      });
+    }
+    return explicit;
+  }
+  const raw = process.env[envName];
+  if (raw === undefined) return fallback;
+  const key = raw.trim().toLowerCase();
+  const truthy = ["1", "true", "on", "yes", "y", "t"];
+  const falsy = ["0", "false", "off", "no", "n", "f", ""];
+  if (truthy.includes(key)) return true;
+  if (falsy.includes(key)) return false;
+  throw new LogConfigurationError(`${envName}=${JSON.stringify(raw)} is not a valid boolean`, {
+    setting: envName,
+    value: raw,
+    accepted: [...truthy, ...falsy],
+  });
 }
 
-/**
- * Structured logger for Tina4.
- *
- * FORMAT IS TEXT BY DEFAULT, and TINA4_LOG_FORMAT=json is the ONLY thing that
- * selects JSON. Nothing else may. Until 3.13.95 an unset TINA4_DEBUG silently
- * flipped BOTH sinks to JSON here, and "production" meant four different things
- * across the four frameworks (Node: !TINA4_DEBUG; Ruby: TINA4_ENV/RACK_ENV/
- * RUBY_ENV == "production"; Python: only configure(production=True); PHP: no
- * switch at all, JSON always) — same machine, same .env, four log formats. That
- * implicit switch is deleted; an object passed as the message is still
- * JSON-encoded INLINE inside the text line, which is the only JSON a default
- * install emits.
- *
- * TINA4_DEBUG still decides COLOUR — a terminal concern, not a format one — so
- * a production pipe gets clean uncoloured bytes and a dev terminal stays
- * readable.
- *
- * Default file-output rule (TINA4_LOG_OUTPUT unset): the log FILE is written
- * only in development. An explicit TINA4_LOG_OUTPUT=file/both, OR an explicit
- * TINA4_LOG_FILE path, always forces a file (explicit wins). stdout is ALWAYS on.
- *
- * Env vars:
- *   TINA4_LOG_FILE          — explicit log file (absolute or relative). Setting it forces a file even in production. Empty = use TINA4_LOG_DIR + tina4.log
- *   TINA4_LOG_DIR           — directory for log files (default: "logs")
- *   TINA4_LOG_FORMAT        — "text" | "json" (default: "text") — the ONLY format switch
- *   TINA4_LOG_OUTPUT        — "stdout" | "file" | "both" (default: "stdout" → file only in dev)
- *   TINA4_LOG_ROTATE_SIZE   — bytes; 0 disables rotation (default: 10485760 = 10MB)
- *   TINA4_LOG_ROTATE_KEEP   — number of historical files to keep (default: 5)
- *   TINA4_LOG_LEVEL         — minimum console level: DEBUG | INFO | WARNING | ERROR | CRITICAL (default: "INFO")
- *   TINA4_LOG_STRICT        — truthy: a log-write failure THROWS instead of being swallowed (default: off)
- *
- * Every one of these is read LAZILY, on each log() call — a script, worker, CLI
- * tool or test that never boots a server still gets the operator's configuration.
- *
- * Rotation is stdlib roll-your-own:
- *   - On each write, statSync the file. If size >= TINA4_LOG_ROTATE_SIZE, rotate.
- *   - app.log.{N-1} → app.log.{N}, …, app.log → app.log.1 via fs.renameSync.
- *   - Files beyond _KEEP are dropped via fs.unlinkSync.
- *   - _SIZE=0 disables rotation entirely.
- */
-export class Log {
-  private static requestId: string | undefined;
-
-  /**
-   * What configure() was explicitly told, held HERE rather than written back
-   * into process.env (ADR-0041).
-   *
-   * configure() used to assign to process.env.TINA4_LOG_DIR / _LOG_FILE. That
-   * reached the right answer -- the argument won -- through a mechanism no
-   * other framework has: it DESTROYED the operator's value for the rest of the
-   * process, and every child process spawned afterwards inherited the
-   * argument instead of what the operator set. Reading configuration must not
-   * write it. Keeping the explicit values in their own slot means resolution
-   * is explicit > env > default with the environment left intact and still
-   * readable.
-   */
-  private static explicitLogDir: string | undefined;
-  private static explicitLogFile: string | undefined;
-
-  /**
-   * Re-read all log-related env vars. Called on every log() so tests that
-   * mutate process.env between calls see the new values without having to
-   * call configure() each time.
-   */
-  private static readEnv(): {
-    logDir: string;
-    logFile: string;
-    rotateSize: number;
-    rotateKeep: number;
-    minLevel: number;
-    format: "text" | "json";
-    output: "stdout" | "file" | "both";
-    fileEnabled: boolean;
-    /** True when the operator named ONE file, so no error.log sibling appears. */
-    explicitFile: boolean;
-    /** TINA4_LOG_STRICT — a failed log write throws instead of being swallowed. */
-    strict: boolean;
-  } {
-    // explicit argument > environment > default (ADR-0041).
-    const logDir = Log.explicitLogDir ?? process.env.TINA4_LOG_DIR ?? DEFAULT_LOG_DIR;
-    const explicitFile = (Log.explicitLogFile ?? process.env.TINA4_LOG_FILE ?? "").trim();
-    const logFile = explicitFile || DEFAULT_LOG_FILE;
-
-    const rawSize = process.env.TINA4_LOG_ROTATE_SIZE;
-    let rotateSize = DEFAULT_ROTATE_SIZE;
-    if (rawSize !== undefined) {
-      const n = parseInt(rawSize, 10);
-      rotateSize = isNaN(n) || n < 0 ? DEFAULT_ROTATE_SIZE : n;
+function resolveInt(
+  explicit: number | undefined,
+  envName: string,
+  fallback: number,
+  minimum: number,
+): number {
+  if (explicit !== undefined) {
+    if (!Number.isInteger(explicit) || explicit < minimum) {
+      throw new LogConfigurationError(`${envName} must be an integer >= ${minimum}`, {
+        setting: envName,
+        value: explicit,
+      });
     }
+    return explicit;
+  }
+  const raw = process.env[envName];
+  if (raw === undefined) return fallback;
+  if (!/^-?\d+$/.test(raw.trim())) {
+    throw new LogConfigurationError(`${envName}=${JSON.stringify(raw)} is not an integer`, {
+      setting: envName,
+      value: raw,
+    });
+  }
+  const n = parseInt(raw, 10);
+  if (n < minimum) {
+    throw new LogConfigurationError(`${envName}=${n} must be >= ${minimum}`, { setting: envName, value: n });
+  }
+  return n;
+}
 
-    const rawKeep = process.env.TINA4_LOG_ROTATE_KEEP;
-    let rotateKeep = DEFAULT_ROTATE_KEEP;
-    if (rawKeep !== undefined) {
-      const n = parseInt(rawKeep, 10);
-      rotateKeep = isNaN(n) || n < 1 ? DEFAULT_ROTATE_KEEP : n;
+/** rotateKeep allows 0 (Decision: rotate_keep=0 discards the old current
+ * entirely rather than renaming it to .1) but never negative or fractional. */
+function resolveRotateKeep(explicit: number | undefined, fallback: number): number {
+  if (explicit !== undefined) {
+    if (!Number.isInteger(explicit) || explicit < 0) {
+      throw new LogConfigurationError("rotateKeep must be a non-negative integer", {
+        setting: "TINA4_LOG_ROTATE_KEEP",
+        value: explicit,
+      });
     }
+    return explicit;
+  }
+  const raw = process.env.TINA4_LOG_ROTATE_KEEP;
+  if (raw === undefined) return fallback;
+  if (!/^-?\d+$/.test(raw.trim())) {
+    throw new LogConfigurationError(`TINA4_LOG_ROTATE_KEEP=${JSON.stringify(raw)} is not an integer`, {
+      setting: "TINA4_LOG_ROTATE_KEEP",
+      value: raw,
+    });
+  }
+  const n = parseInt(raw, 10);
+  if (n < 0) {
+    throw new LogConfigurationError(`TINA4_LOG_ROTATE_KEEP=${n} must not be negative`, {
+      setting: "TINA4_LOG_ROTATE_KEEP",
+      value: n,
+    });
+  }
+  return n;
+}
 
-    // v3.13.14: default level INFO (was DEBUG) — parity with Python/PHP/Ruby;
-    // surfaces request/startup/warn/error without debug noise in deploys.
-    const levelEnv = (process.env.TINA4_LOG_LEVEL ?? "INFO").toUpperCase();
-    const minLevel = LEVEL_PRIORITY[levelEnv as LogLevel] ?? 0;
-
-    const fmt = (process.env.TINA4_LOG_FORMAT ?? "text").trim().toLowerCase();
-    const format: "text" | "json" = fmt === "json" ? "json" : "text";
-
-    const out = (process.env.TINA4_LOG_OUTPUT ?? "stdout").trim().toLowerCase();
-    let output: "stdout" | "file" | "both" = "stdout";
-    if (out === "file") output = "file";
-    else if (out === "both") output = "both";
-
-    // v3.13.39: dev/prod-aware default file output (Python master, 4c6d881).
-    // When TINA4_LOG_OUTPUT is unset (default "stdout"), the log FILE is written
-    // only in development (TINA4_DEBUG truthy). In production / containers the
-    // logger is stdout-only — writing logs/tina4.log inside a container just
-    // bloats the writable layer + disk, and 12-factor wants logs on stdout for
-    // the platform to capture. Explicit TINA4_LOG_OUTPUT=file/both OR an explicit
-    // TINA4_LOG_FILE path always wins (explicit forces a file regardless of env).
-    let fileEnabled: boolean;
-    if (output === "file" || output === "both") {
-      fileEnabled = true;
-    } else if (explicitFile !== "") {
-      fileEnabled = true;
-    } else {
-      fileEnabled = !Log.isProduction();
+function checkRemovedSettings(): void {
+  for (const [name, detail] of Object.entries(REMOVED_SETTINGS)) {
+    if (process.env[name] !== undefined) {
+      throw new LogConfigurationError(`${name} is a removed setting (${detail})`, {
+        setting: name,
+        value: process.env[name],
+      });
     }
+  }
+}
 
-    // TINA4_LOG_STRICT — documented on all four env-var pages, implemented only
-    // in Ruby until 3.13.95: a documented no-op in three frameworks. When truthy
-    // a log-write failure THROWS instead of being swallowed, so a deploy whose
-    // log directory is read-only fails loudly instead of running blind.
-    const strict = isTruthy(process.env.TINA4_LOG_STRICT);
+function isProduction(): boolean {
+  return !isTruthy(process.env.TINA4_DEBUG);
+}
 
-    return {
-      logDir, logFile, rotateSize, rotateKeep, minLevel, format, output, fileEnabled,
-      explicitFile: explicitFile !== "",
-      strict,
-    };
+/**
+ * Resolve one fully-validated configuration snapshot from explicit options,
+ * then environment, then default (ADR-0041) — WITHOUT touching the
+ * filesystem. Every invalid setting throws LogConfigurationError before this
+ * function returns, so a caller (configure() or the lazy first-use path)
+ * commits nothing on a validation failure (LOG-C07, LOG-V01..V05).
+ */
+function resolveSnapshot(options: ConfigureOptions): Omit<Snapshot, "mainSink" | "errorSink"> {
+  checkRemovedSettings();
+
+  const level = options.level !== undefined
+    ? parseLevel(options.level, "level")
+    : process.env.TINA4_LOG_LEVEL !== undefined
+      ? parseLevel(process.env.TINA4_LOG_LEVEL, "TINA4_LOG_LEVEL")
+      : DEFAULT_LEVEL;
+
+  const fileLevel = options.fileLevel !== undefined
+    ? parseLevel(options.fileLevel, "fileLevel")
+    : process.env.TINA4_LOG_FILE_LEVEL !== undefined
+      ? parseLevel(process.env.TINA4_LOG_FILE_LEVEL, "TINA4_LOG_FILE_LEVEL")
+      : DEFAULT_FILE_LEVEL;
+
+  // Format is DEBUG-DERIVED (Decision 3): explicit TINA4_LOG_FORMAT wins;
+  // otherwise truthy TINA4_DEBUG selects text, else json.
+  let format: "text" | "json";
+  const explicitFormat = options.format ?? process.env.TINA4_LOG_FORMAT;
+  if (explicitFormat !== undefined) {
+    const f = explicitFormat.trim().toLowerCase();
+    if (f !== "text" && f !== "json") {
+      throw new LogConfigurationError(`TINA4_LOG_FORMAT=${JSON.stringify(explicitFormat)} is not valid`, {
+        setting: "TINA4_LOG_FORMAT",
+        value: explicitFormat,
+        accepted: ["text", "json"],
+      });
+    }
+    format = f;
+  } else {
+    format = isTruthy(process.env.TINA4_DEBUG) ? "text" : "json";
   }
 
-  /**
-   * The single console-threshold predicate: does a message at `level` clear
-   * the configured minimum console level? This is the ONE place level
-   * comparison lives — both the live log() gate and the public isEnabled()
-   * predicate call it, so they can never disagree about what actually prints.
-   */
-  private static passesThreshold(level: LogLevel, minLevel: number): boolean {
-    return (LEVEL_PRIORITY[level] ?? 0) >= minLevel;
+  // Output: an explicit value (stdout/file/both) ALWAYS wins, full stop —
+  // naming a file (below) never itself enables the file sink (LOG-C08).
+  let outputSelector: "stdout" | "file" | "both";
+  const explicitOutput = options.output ?? process.env.TINA4_LOG_OUTPUT;
+  if (explicitOutput !== undefined) {
+    const o = explicitOutput.trim().toLowerCase();
+    if (o !== "stdout" && o !== "file" && o !== "both") {
+      throw new LogConfigurationError(`TINA4_LOG_OUTPUT=${JSON.stringify(explicitOutput)} is not valid`, {
+        setting: "TINA4_LOG_OUTPUT",
+        value: explicitOutput,
+        accepted: ["stdout", "file", "both"],
+      });
+    }
+    outputSelector = o;
+  } else {
+    // Unset: dev/prod-aware default — file only in development.
+    outputSelector = isProduction() ? "stdout" : "both";
   }
+  const stdoutEnabled = outputSelector !== "file";
+  const fileEnabled = outputSelector !== "stdout";
 
-  /**
-   * Return true if a message at `level` would pass the configured minimum
-   * console level (TINA4_LOG_LEVEL) — the same threshold that gates stdout.
-   *
-   * This reflects CONSOLE (stdout) visibility only. The log file always
-   * records every level regardless of this threshold, so don't use it to
-   * decide whether something gets persisted — use it to skip building an
-   * expensive payload that would not be shown:
-   *
-   *     if (Log.isEnabled("debug")) {
-   *       Log.debug("state", expensiveSnapshot());
-   *     }
-   *
-   * `level` is case-insensitive. "critical" is the highest severity (priority
-   * 4 > error 3) and flows through the ordinary threshold check like every
-   * other level — there is no toggle. It reuses the same passesThreshold()
-   * check the logger itself uses, so it never drifts from what print does.
-   */
-  static isEnabled(level: string): boolean {
-    const cfg = Log.readEnv();
-    const lvl = (level ?? "").toUpperCase() as LogLevel;
-    return Log.passesThreshold(lvl, cfg.minLevel);
+  const rotateSize = resolveInt(options.rotateSize, "TINA4_LOG_ROTATE_SIZE", DEFAULT_ROTATE_SIZE, MIN_ROTATE_SIZE);
+  const rotateKeep = resolveRotateKeep(options.rotateKeep, DEFAULT_ROTATE_KEEP);
+  const strict = resolveBool(options.strict, "TINA4_LOG_STRICT", false);
+  const callerCapture = resolveBool(options.caller, "TINA4_LOG_FUNC", false);
+
+  const dirRaw = options.logDir ?? process.env.TINA4_LOG_DIR ?? DEFAULT_LOG_DIR;
+  if (dirRaw === "") {
+    throw new LogConfigurationError("logDir must not be empty", { setting: "TINA4_LOG_DIR", value: dirRaw });
+  }
+  const fileRaw = options.logFile ?? process.env.TINA4_LOG_FILE ?? "";
+  // A NUL byte can never be part of a real path (the underlying syscalls
+  // reject it), but that would otherwise only surface at OPEN time -- and
+  // only when the file sink ends up enabled. Reject it here, unconditionally,
+  // so a malformed path fails CONFIGURATION regardless of whether output
+  // happens to resolve to a sink that would ever touch the filesystem.
+  if (dirRaw.includes("\0") || fileRaw.includes("\0")) {
+    throw new LogConfigurationError("log path must not contain a NUL byte", {
+      setting: dirRaw.includes("\0") ? "TINA4_LOG_DIR" : "TINA4_LOG_FILE",
+    });
   }
 
-  /**
-   * Set the current request ID for log correlation.
-   */
-  static setRequestId(id: string | undefined): void {
-    Log.requestId = id;
+  const projectRoot = process.cwd();
+  let dirCandidate = dirRaw;
+  let fileCandidate = fileRaw;
+  if (!fileCandidate && targetIsFile(dirCandidate)) {
+    fileCandidate = basename(dirCandidate);
+    dirCandidate = dirname(dirCandidate);
   }
 
-  /**
-   * Get the current request ID.
-   */
-  static getRequestId(): string | undefined {
-    return Log.requestId;
+  const resolvedLogDir = (isAbsolute(dirCandidate) ? dirCandidate : join(projectRoot, dirCandidate)).replace(/\/$/, "");
+
+  let resolvedLogFile: string | null;
+  let layout: "directory" | "single";
+  if (fileCandidate) {
+    resolvedLogFile = isAbsolute(fileCandidate) ? fileCandidate : join(resolvedLogDir, fileCandidate);
+    layout = "single";
+  } else {
+    resolvedLogFile = null;
+    layout = "directory";
   }
 
-  /**
-   * Configure where logs are written.
-   *
-   * Logs land in a `logs/` folder by default. The argument OVERRIDES that, and
-   * it accepts a DIRECTORY or a FILE PATH:
-   *
-   *   configure()                              -> ./logs/tina4.log + ./logs/error.log
-   *   configure("/var/log/myapp")              -> /var/log/myapp/tina4.log + error.log
-   *   configure("/var/log/myapp/app.log")      -> that exact file (no error.log sibling)
-   *   configure({ logDir, logFile })           -> the explicit object form still works
-   *
-   * A plain string used to be accepted and silently ignored, because only the
-   * object form was read - so the call that works in the other three
-   * frameworks produced no log file here and said nothing (feature 2 of the
-   * audit, D4). Both forms now work.
-   */
-  static configure(options?: string | { logDir?: string; logFile?: string }): void {
-    // Record what the caller asked for; never write it back into process.env
-    // (ADR-0041 -- reading configuration must not write it).
-    if (typeof options === "string") {
-      if (targetIsFile(options)) {
-        Log.explicitLogDir = dirname(options);
-        Log.explicitLogFile = options;
-      } else {
-        Log.explicitLogDir = options;
-      }
-      Log.applyAppendMode();
-      return;
-    }
-    if (options) {
-      if (options.logDir) Log.explicitLogDir = options.logDir;
-      if (options.logFile) Log.explicitLogFile = options.logFile;
+  return {
+    level,
+    fileLevel,
+    format,
+    stdoutEnabled,
+    fileEnabled,
+    outputSelector,
+    logDir: resolvedLogDir,
+    logFile: resolvedLogFile,
+    layout,
+    rotateSize,
+    rotateKeep,
+    strict,
+    callerCapture,
+  };
+}
+
+// ============================================================================
+// Log — the public class.
+// ============================================================================
+
+let activeSnapshot: Snapshot | null = null;
+
+/** Lazily resolve (and CACHE) the effective configuration on first use
+ * (LOG-C01/L2). Once resolved the snapshot is STABLE: a later environment
+ * mutation does not retroactively change it (LOG-C05) until reset() (LOG-C06). */
+function ensureSnapshot(): Snapshot {
+  if (activeSnapshot) return activeSnapshot;
+  const resolved = resolveSnapshot({});
+  activeSnapshot = openSinks(resolved);
+  return activeSnapshot;
+}
+
+function openSinks(resolved: Omit<Snapshot, "mainSink" | "errorSink">): Snapshot {
+  let mainSink: LogFileSink | null = null;
+  let errorSink: LogFileSink | null = null;
+  if (resolved.fileEnabled) {
+    if (resolved.layout === "single") {
+      mainSink = new LogFileSink(resolved.logFile!, resolved.rotateSize, resolved.rotateKeep);
+      mainSink.open();
+    } else {
+      mainSink = new LogFileSink(join(resolved.logDir, DEFAULT_LOG_FILE_NAME), resolved.rotateSize, resolved.rotateKeep);
+      mainSink.open();
+      errorSink = new LogFileSink(join(resolved.logDir, "error.log"), resolved.rotateSize, resolved.rotateKeep);
+      errorSink.open();
     }
-    Log.applyAppendMode();
   }
+  return { ...resolved, mainSink, errorSink };
+}
+
+function stdoutIsTty(): boolean {
+  return process.stdout.isTTY === true;
+}
 
+export class Log {
   /**
-   * Forget what configure() was told, so resolution falls back to the
-   * environment and then the built-in defaults. Parity with PHP's Log::reset().
+   * Configure the logger. Two-phase and transactional: the WHOLE candidate
+   * configuration is resolved and validated first (LOG-C07 — a bad setting
+   * never touches the filesystem and never disturbs the prior snapshot),
+   * then its sinks are opened (LOG-E01 — an inaccessible sink fails
+   * configuration, still without replacing the prior snapshot), and only on
+   * full success does it become the active configuration.
    *
-   * This exists because the explicit values are now HELD here rather than
-   * written back into process.env, and that makes them STICKY for the life of
-   * the process -- which is right for an application (configure() at boot is
-   * the operator's instruction and a later stray env write should not silently
-   * re-point the logs) and wrong for a long-lived test process that wants to
-   * drive the logger purely from the environment afterwards.
+   *   Log.configure()                                    -> logs/tina4.log + logs/error.log
+   *   Log.configure({ logDir: "/var/log/myapp" })        -> /var/log/myapp/tina4.log + error.log
+   *   Log.configure({ logFile: "/var/log/myapp/app.log" }) -> that exact file, no error.log sibling
+   *   Log.configure({ level: "debug", format: "text", output: "both", strict: true, caller: true })
    *
-   * I removed this method once for having no callers. That was correct about
-   * the grep and wrong about the code: the full suite is the caller. Before the
-   * explicit slots existed, configure() ASSIGNED to process.env, so a later
-   * direct assignment simply overwrote it and env-driven cases kept working by
-   * accident. test/logger.test.ts depends on exactly that -- it configures a
-   * file early, then runs the whole default-output block off the environment
-   * (see its own note: "these cases must NOT route through Log.configure").
-   * Three of those cases failed on the lab until this came back.
-   */
-  static reset(): void {
-    Log.explicitLogDir = undefined;
-    Log.explicitLogFile = undefined;
-  }
-
-  /**
-   * TINA4_LOG_APPEND — append (default) or overwrite on startup.
+   * A plain string is also accepted as shorthand for `{ logDir: string }` —
+   * or `{ logFile: string }` when it looks like a file (has an extension and
+   * is not an existing directory), via the same targetIsFile heuristic
+   * configure() itself uses to split a bare TINA4_LOG_DIR that names a file.
    *
-   * APPEND IS THE DEFAULT: a log you can lose by restarting the process is not
-   * a log. Set it false for one file per run (a short CLI, a test fixture, a
-   * container shipping logs elsewhere); the files are truncated once here at
-   * configure time, never per line.
+   *   Log.configure("/var/log/myapp")          -> same as { logDir: "/var/log/myapp" }
+   *   Log.configure("/var/log/myapp/app.log")  -> same as { logFile: "/var/log/myapp/app.log" }
    */
-  private static applyAppendMode(): void {
-    const raw = process.env.TINA4_LOG_APPEND;
-    const append = raw === undefined || isTruthy(raw);
-    if (append) return;
-    const cfg = Log.readEnv();
-    const targets = cfg.explicitFile
-      ? [resolveLogFilePath(cfg.logDir, cfg.logFile)]
-      : [resolveLogFilePath(cfg.logDir, cfg.logFile), join(cfg.logDir, "error.log")];
-    for (const path of targets) {
-      try {
-        if (existsSync(path)) writeFileSync(path, "", "utf-8");
-      } catch (err) {
-        // Same TINA4_LOG_STRICT contract as writeToFile: this IS a write to the
-        // log file, so under strict it must not be swallowed either.
-        if (cfg.strict) throw err;
-        /* logging must never crash the app */
-      }
-    }
+  static configure(options: string | ConfigureOptions = {}): void {
+    const normalized: ConfigureOptions = typeof options === "string"
+      ? (targetIsFile(options) ? { logFile: options } : { logDir: options })
+      : options;
+    const resolved = resolveSnapshot(normalized);
+    activeSnapshot = openSinks(resolved);
   }
 
-  /** Log an informational message. */
-  static info(message: unknown, data?: unknown): void {
-    Log.log("INFO", message, data);
+  /** Forget the active configuration; the next use resolves fresh from the
+   * environment. Idempotent. */
+  static reset(): void {
+    activeSnapshot = null;
+    requestIdStore.disable?.();
+    requestIdFallback = undefined;
   }
 
-  /** Log a debug message. */
-  static debug(message: unknown, data?: unknown): void {
-    Log.log("DEBUG", message, data);
+  /** A defensive copy of the effective, stable configuration (LOG-C10). */
+  static configuration(): Record<string, unknown> {
+    const s = ensureSnapshot();
+    return {
+      level: s.level,
+      file_level: s.fileLevel,
+      format: s.format,
+      output: s.outputSelector,
+      log_dir: s.logDir,
+      log_file: s.logFile,
+      layout: s.layout,
+      rotate_size: s.rotateSize,
+      rotate_keep: s.rotateKeep,
+      strict: s.strict,
+      caller: s.callerCapture,
+      stdout_enabled: s.stdoutEnabled,
+      file_enabled: s.fileEnabled,
+    };
   }
 
-  /** Log a warning message. */
-  static warning(message: unknown, data?: unknown): void {
-    Log.log("WARNING", message, data);
-  }
+  // ── request id (Decision 12 — AsyncLocalStorage) ─────────────────────
 
-  /** Backwards-compat alias for warning(). */
-  static warn(message: unknown, data?: unknown): void {
-    Log.log("WARNING", message, data);
+  /** Run `fn` with `id` established as the request-scoped correlation id.
+   * Every log line inside `fn` — across every await — carries `id`, and two
+   * concurrent requests each keep their own; the id needs no explicit clear
+   * because it is scoped to this call, not to shared mutable state. */
+  static runWithRequestId<T>(id: string | undefined, fn: () => T): T {
+    return requestIdStore.run({ id }, fn);
   }
 
-  /** Log an error message. */
-  static error(message: unknown, data?: unknown): void {
-    Log.log("ERROR", message, data);
+  static setRequestId(id: string | undefined): void {
+    const store = requestIdStore.getStore();
+    if (store) store.id = id;
+    else requestIdFallback = id;
   }
 
-  /**
-   * Log a critical message. CRITICAL is the highest severity (priority 4 >
-   * error 3) and ALWAYS emits like every other level — subject only to the
-   * console threshold, which it always passes at normal levels — and is always
-   * persisted to the log file (Node tees every level to a single tina4.log;
-   * critical 4 >= warning 2 so it would be in error.log on a split-file model).
-   * Matches Python master parity — there is no enable toggle.
-   */
-  static critical(message: unknown, data?: unknown): void {
-    Log.log("CRITICAL", message, data);
+  static getRequestId(): string | undefined {
+    const store = requestIdStore.getStore();
+    return store ? store.id : requestIdFallback;
   }
 
-  /** Check if running in production mode (TINA4_DEBUG is not truthy). */
-  private static isProduction(): boolean {
-    return !isTruthy(process.env.TINA4_DEBUG);
+  /** Explicitly end a request's correlation scope (LOG-Q01/A01 public
+   * surface). Equivalent to setRequestId(undefined) but named for parity
+   * with the other three frameworks' clear_request_id. */
+  static clearRequestId(): void {
+    Log.setRequestId(undefined);
   }
 
-  /** Get current ISO timestamp */
-  private static timestamp(): string {
-    return new Date().toISOString();
+  static sanitizeRequestId(value: string | string[] | undefined | null): string | undefined {
+    if (value === undefined || value === null) return undefined;
+    const raw = Array.isArray(value) ? value.join(",") : value;
+    if (raw.length === 0 || raw.length > 128) return undefined;
+    if (/[^A-Za-z0-9._-]/.test(raw)) return undefined;
+    return raw;
   }
 
-  /** Ensure the log directory exists */
-  private static ensureLogDir(filePath: string): void {
-    const dir = dirname(filePath);
-    if (!existsSync(dir)) {
-      mkdirSync(dir, { recursive: true });
-    }
-  }
+  // ── threshold ──────────────────────────────────────────────────────
 
   /**
-   * Roll-your-own rotation, stdlib only.
-   *
-   * Sequence on each write:
-   *   1. statSync the current file. If size < rotateSize, return.
-   *   2. Drop any file beyond keep via unlinkSync (cap the historical count).
-   *   3. Atomic shift: app.log.{N-1} → app.log.{N}, …, app.log.1 → app.log.2.
-   *   4. Rename current app.log → app.log.1.
-   *   5. Truncate via writeFileSync(path, "") so subsequent appends start fresh.
-   *
-   * Sync calls per write are fine — the worst case is contention on a single
-   * file, and the OS atomically serialises rename/unlink anyway.
-   *
-   * `rotateSize` of 0 disables rotation entirely.
+   * True when `level` passes the queried sink's threshold and that sink is
+   * active. `sink` is undefined/"console"/"stdout" (console — the historical
+   * meaning) or "file" (Decision 8: the file sink has its own independent
+   * TINA4_LOG_FILE_LEVEL threshold).
    */
-  private static rotateIfNeeded(filePath: string, rotateSize: number, rotateKeep: number): void {
-    if (rotateSize <= 0) return;
-    if (!existsSync(filePath)) return;
-
-    let size = 0;
-    try {
-      size = statSync(filePath).size;
-    } catch {
-      return;
+  static isEnabled(level: string, sink?: "console" | "stdout" | "file"): boolean {
+    if (level === undefined || level === null) {
+      throw new LogArgumentError("isEnabled requires a level", { argument: "level" });
     }
-    if (size < rotateSize) return;
-
-    // Drop files beyond keep
-    for (let n = rotateKeep + 1; n <= rotateKeep + 10; n++) {
-      const stale = `${filePath}.${n}`;
-      if (existsSync(stale)) {
-        try { unlinkSync(stale); } catch { /* ignore */ }
-      } else {
-        break;
-      }
+    const key = String(level).trim().toUpperCase() as LogLevel;
+    if (!(key in LEVELS)) {
+      throw new LogArgumentError(`${JSON.stringify(level)} is not a valid level`, {
+        argument: "level",
+        accepted: Object.keys(LEVELS),
+      });
     }
-
-    // Drop the oldest in-window file if at capacity
-    const oldest = `${filePath}.${rotateKeep}`;
-    if (existsSync(oldest)) {
-      try { unlinkSync(oldest); } catch { /* ignore */ }
+    const s = ensureSnapshot();
+    if (sink === undefined || sink === "console" || sink === "stdout") {
+      return s.stdoutEnabled && LEVELS[key] >= LEVELS[s.level];
     }
-
-    // Shift: .{N-1} -> .{N}, ..., .1 -> .2
-    for (let n = rotateKeep - 1; n >= 1; n--) {
-      const src = `${filePath}.${n}`;
-      const dst = `${filePath}.${n + 1}`;
-      if (existsSync(src)) {
-        try { renameSync(src, dst); } catch { /* ignore */ }
-      }
+    if (sink === "file") {
+      return s.fileEnabled && LEVELS[key] >= LEVELS[s.fileLevel];
     }
-
-    // Move current → .1, then truncate
-    try { renameSync(filePath, `${filePath}.1`); } catch { /* ignore */ }
-    try { writeFileSync(filePath, "", "utf-8"); } catch { /* ignore */ }
+    throw new LogArgumentError(`${JSON.stringify(sink)} is not a valid sink`, {
+      argument: "sink",
+      accepted: ["console", "file"],
+    });
   }
 
-  /**
-   * Write a line to the log file, stripping ANSI codes.
-   *
-   * A failure is swallowed by default — logging must never crash the app. With
-   * TINA4_LOG_STRICT truthy it is RE-THROWN instead: an app that believes it is
-   * writing an audit trail into a read-only directory, and is not, is worse off
-   * than one that dies at the first line. Same contract in all four frameworks.
-   */
-  private static writeToFile(
-    filePath: string,
-    line: string,
-    rotateSize: number,
-    rotateKeep: number,
-    strict: boolean,
-  ): void {
-    try {
-      Log.ensureLogDir(filePath);
-      Log.rotateIfNeeded(filePath, rotateSize, rotateKeep);
-      appendFileSync(filePath, stripAnsi(line) + "\n", "utf-8");
-    } catch (err) {
-      if (strict) throw err;
-      // Silently fail — logging should never crash the app
-    }
-  }
+  // ── event methods (Decision 23) ──────────────────────────────────────
 
-  /** Core log method */
-  private static log(level: LogLevel, rawMessage: unknown, data?: unknown): void {
-    const cfg = Log.readEnv();
+  static debug(message: unknown, context?: unknown): void {
+    Log.emit("DEBUG", message, context);
+  }
 
-    // Coerce FIRST, into the local the human line is built from further down.
-    // Anything can arrive as a message: an object from a handler, a Buffer off
-    // a socket, a 10MB string. See coerceMessage.
-    const message = coerceMessage(rawMessage);
+  static info(message: unknown, context?: unknown): void {
+    Log.emit("INFO", message, context);
+  }
 
-    const entry: LogEntry = {
-      timestamp: Log.timestamp(),
-      level,
-      message,
-    };
+  static warning(message: unknown, context?: unknown): void {
+    Log.emit("WARNING", message, context);
+  }
 
-    if (Log.requestId) {
-      entry.request_id = Log.requestId;
-    }
+  static error(message: unknown, context?: unknown): void {
+    Log.emit("ERROR", message, context);
+  }
 
-    // Caller-name injection — opt-in via TINA4_LOG_FUNC=true. Off by default
-    // so existing log output stays byte-identical for users who haven't asked
-    // for it. Parity feature across all four Tina4 frameworks.
-    const fnName = callerName();
-    if (fnName) {
-      entry.function = fnName;
-    }
+  /** Highest severity. Always emits, subject only to the configured
+   * threshold — there is no separate enable toggle. */
+  static critical(message: unknown, context?: unknown): void {
+    Log.emit("CRITICAL", message, context);
+  }
 
-    if (data !== undefined) {
-      entry.context = data;
+  private static emit(level: EventLevel, rawMessage: unknown, rawContext: unknown): void {
+    const s = ensureSnapshot();
+    const consoleOk = s.stdoutEnabled && LEVELS[level] >= LEVELS[s.level];
+    const fileOk = s.fileEnabled && LEVELS[level] >= LEVELS[s.fileLevel];
+    if (!consoleOk && !fileOk) return;
+
+    const requestId = Log.getRequestId();
+    const callerName = s.callerCapture ? resolveCallerName() : undefined;
+    const event = buildEvent(level, rawMessage, requestId, callerName, rawContext);
+
+    if (consoleOk) {
+      const line = boundedForSink(event, s.format, STDOUT_MAX_BYTES).replace(/\n$/, "");
+      const plain = s.format === "json" || !stdoutIsTty();
+      const text = plain ? line : `${COLORS[level]}${line}${RESET}`;
+      // console.log (not a direct process.stdout.write) — interceptable by
+      // reassigning console.log, which is how both this codebase's own tests
+      // and application code conventionally capture/redirect log output; it
+      // still ultimately writes to stdout when not overridden.
+      console.log(text);
     }
 
-    // Build human-readable line
-    const paddedLevel = level.padEnd(8);
-    const reqPart = Log.requestId ? ` [${Log.requestId}]` : "";
-    const fnPart = fnName ? ` [${fnName}]` : "";
-    const dataPart = data !== undefined ? ` ${JSON.stringify(data)}` : "";
-    const humanLine = `${entry.timestamp} [${paddedLevel}]${reqPart}${fnPart} ${message}${dataPart}`;
-
-    // ONE format decision, both sinks, one input: TINA4_LOG_FORMAT. Text is the
-    // default; only an explicit `json` selects JSON. The `|| Log.isProduction()`
-    // that used to live here made an UNSET TINA4_DEBUG silently reformat every
-    // line — the owner's measured defect (four frameworks, four meanings of
-    // "production", four different formats off one .env). An object passed as
-    // the message is still JSON-encoded INLINE by coerceMessage, which is the
-    // only structure a default install emits.
-    const formattedLine = cfg.format === "json" ? JSON.stringify(entry) : humanLine;
-
-    const shouldLog = Log.passesThreshold(level, cfg.minLevel);
-
-    // Console output. v3.13.14: stdout is NOT suppressed in production —
-    // containers read PID 1 stdout (docker logs / k8s) and the old
-    // `!isProduction()` gate meant deployed apps logged nothing.
-    // TINA4_LOG_OUTPUT="file" still opts out of stdout entirely.
-    //
-    // stdout carries the SAME formattedLine as the file — the format env is the
-    // only thing that picks text vs JSON. TINA4_DEBUG decides COLOUR only: ANSI
-    // is for a human at a terminal, and a production pipe / log shipper must get
-    // clean bytes. Truncate on the CONSOLE only; the file keeps the full line so
-    // a consumer parsing it loses nothing, and a terminal does not need 10MB.
-    if (shouldLog && cfg.output !== "file") {
-      const consoleLine = truncateForStdout(formattedLine);
-      if (Log.isProduction()) {
-        console.log(consoleLine);
-      } else {
-        console.log(`${COLORS[level]}${consoleLine}${RESET}`);
+    if (fileOk && s.mainSink) {
+      const mainLine = boundedForSink(event, s.format, s.rotateSize);
+      writeSink(s.mainSink, mainLine, s.strict);
+      if (s.layout === "directory" && s.errorSink && LEVELS[level] >= LEVELS.WARNING) {
+        writeSink(s.errorSink, mainLine, s.strict);
       }
     }
+  }
+}
 
-    // File output (v3.13.39 — Python master, 4c6d881): gated on cfg.fileEnabled.
-    //
-    //   output=stdout (default): file ONLY in dev (TINA4_DEBUG truthy);
-    //                            production / containers are stdout-only — no
-    //                            file to bloat the writable layer / disk.
-    //   output=file              file only — no console (always writes a file)
-    //   output=both              file + console (always writes a file)
-    //   explicit TINA4_LOG_FILE  always writes a file (explicit wins)
-    //
-    // readEnv() resolves all of the above into cfg.fileEnabled, so flipping
-    // that one flag gates the whole file writer (the only persisted sink).
-    if (cfg.fileEnabled) {
-      const filePath = resolveLogFilePath(cfg.logDir, cfg.logFile);
-      Log.writeToFile(filePath, formattedLine, cfg.rotateSize, cfg.rotateKeep, cfg.strict);
-
-      // Mirror WARNING and above into a dedicated error.log so
-      // `tail -f logs/error.log` gives just the stuff worth looking at. Node
-      // wrote ONE file where Python and PHP wrote two, so anyone whose
-      // alerting tails error.log got silence here (feature 2 of the audit, D3).
-      // Skipped when the operator named ONE file explicitly: they asked for a
-      // single path, so a sibling error.log appearing beside it is a surprise.
-      if (!cfg.explicitFile && LEVEL_PRIORITY[level] >= LEVEL_PRIORITY.WARNING) {
-        const errorPath = join(cfg.logDir, "error.log");
-        Log.writeToFile(errorPath, formattedLine, cfg.rotateSize, cfg.rotateKeep, cfg.strict);
-      }
-    }
+function writeSink(sink: LogFileSink, line: string, strict: boolean): void {
+  try {
+    sink.write(line);
+  } catch (err) {
+    if (strict) throw err;
+    const msg = err instanceof Error ? err.message : String(err);
+    console.log(`tina4: log sink ${sink.path} failed: ${msg}`);
   }
 }