tina4ruby 3.13.97 → 3.13.99

data/lib/tina4/log.rb

@@ -2,575 +2,742 @@
 
 require "fileutils"
 require "json"
-require "logger"
+require "digest"
 
 module Tina4
-  module Log
-    LEVELS = {
-      "[TINA4_LOG_ALL]" => 0,
-      "[TINA4_LOG_DEBUG]" => 0,
-      "[TINA4_LOG_INFO]" => 1,
-      "[TINA4_LOG_WARNING]" => 2,
-      "[TINA4_LOG_ERROR]" => 3,
-      "[TINA4_LOG_CRITICAL]" => 4,
-      "[TINA4_LOG_NONE]" => 5
-    }.freeze
+  # Invalid setting, removed setting, or an inaccessible selected sink.
+  class LogConfigurationError < ArgumentError
+    attr_accessor :setting, :value, :accepted, :sink, :operation
+
+    def initialize(message, setting: nil, value: nil, accepted: nil, sink: nil, operation: nil)
+      super(message)
+      @setting = setting
+      @value = value
+      @accepted = accepted
+      @sink = sink
+      @operation = operation
+    end
+  end
 
-    SEVERITY_MAP = {
-      debug: 0, info: 1, warn: 2, error: 3, critical: 4
-    }.freeze
+  # Invalid argument to a public logger method.
+  class LogArgumentError < ArgumentError
+    attr_accessor :argument, :accepted
 
-    COLORS = {
-      reset: "\e[0m", red: "\e[31m", green: "\e[32m",
-      yellow: "\e[33m", blue: "\e[34m", magenta: "\e[35m",
-      cyan: "\e[36m", gray: "\e[90m"
-    }.freeze
+    def initialize(message, argument: nil, accepted: nil)
+      super(message)
+      @argument = argument
+      @accepted = accepted
+    end
+  end
 
-    # ANSI escape code regex for stripping from file output
-    ANSI_RE = /\033\[[0-9;]*m/
+  # A selected sink failed after configuration succeeded, under strict mode.
+  class LogWriteError < RuntimeError
+    attr_accessor :sink, :operation
 
-    # The logger must never be surprised by what it is handed. Console lines are
-    # capped; control characters never reach a terminal. Same numbers in all four
-    # frameworks (feature 2 of the feature audit).
-    STDOUT_MAX_CHARS = 2000
-    CONTROL_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/
+    def initialize(message, sink: nil, operation: nil)
+      super(message)
+      @sink = sink
+      @operation = operation
+    end
+  end
 
-    # Defaults used when env vars are unset.
-    DEFAULT_ROTATE_SIZE = 10 * 1024 * 1024 # 10MB
-    DEFAULT_ROTATE_KEEP = 5
+  # One owned log file: bounded, PREDICTIVE rotation guarded by a single
+  # in-process (thread) exclusive lock over the size check, rotation and
+  # append.
+  #
+  # Decision 20 (2026-08-10 owner override): SINGLE FILE + IN-PROCESS LOCK
+  # ONLY. Cross-process exclusive locking is deliberately not implemented;
+  # concurrent PROCESSES writing the same file may interleave. Run one file
+  # per process, or route through a log shipper, for that case.
+  class LogFileSink
+    LOCK_TIMEOUT_SECONDS = 2.0
+
+    attr_reader :path
+
+    def initialize(path, rotate_size, rotate_keep)
+      @path = path
+      @rotate_size = rotate_size
+      @rotate_keep = rotate_keep
+      @mutex = Mutex.new
+    end
 
-    # The error classes TINA4_LOG_STRICT must let ESCAPE stdlib ::Logger.
-    #
-    # TINA4_LOG_STRICT is documented as "raise on a log write failure instead of
-    # swallowing", and #write_to_file dutifully rescues IOError/SystemCallError
-    # and re-raises when @strict. It was a NO-OP anyway: ::Logger::LogDevice
-    # wraps every device write in its own `handle_write_errors`, which rescues
-    # and turns the failure into a bare `warn` on stderr. The real error was
-    # swallowed one layer BELOW Tina4 and never reached Tina4's rescue at all.
-    #
-    # MEASURED 2026-08-01 on a genuinely full 1MB HFS+ ram disk (0 KB free),
-    # Ruby 4.0.2: with TINA4_LOG_STRICT=true, Tina4::Log.info(...) printed
-    # "log writing failed. No space left on device @ rb_sys_fail_on_write" to
-    # stderr and returned normally. The operator got a stderr warning and strict
-    # mode did nothing.
-    #
-    # ::Logger has a first-class seam for exactly this — `reraise_write_errors:`
-    # (logger >= 1.5.0), which handle_write_errors re-raises through instead of
-    # warning. Listing the two classes #write_to_file already rescues keeps the
-    # two ends of the strict path in agreement. Note Errno::ENOSPC (and every
-    # other errno) is a SystemCallError, so the real disk-full case is covered.
-    STRICT_WRITE_ERRORS = [IOError, SystemCallError].freeze
-
-    # A log device that writes ONLY log lines.
-    #
-    # stdlib ::Logger stamps a banner as the FIRST LINE of every file it creates
-    # — and it creates one on every rotation too:
-    #
-    #   # Logfile created on 2026-08-01 21:49:10 +0200 by logger.rb/v1.7.0
-    #
-    # In JSON mode (TINA4_LOG_FORMAT=json) that is not JSON, so any line-oriented
-    # shipper — Filebeat, Fluent Bit, Vector, promtail, `jq -c` — fails on line 1
-    # of every file and every rotated file. It is a Ruby-only artifact: no other
-    # Tina4 framework emits it, so a JSON pipeline that works on Python/PHP/Node
-    # breaks here and nowhere else.
-    #
-    # Suppressing it in the DEVICE (rather than pre-creating the file) covers
-    # rotation as well, and keeps ::Logger's own rotation/locking untouched —
-    # add_log_header is the single method whose whole body is that banner.
-    class HeaderlessLogDevice < ::Logger::LogDevice
-      def add_log_header(file); end
+    # Create the directory and prove the file is writable.
+    def open
+      dir = File.dirname(@path)
+      FileUtils.mkdir_p(dir)
+      File.open(@path, "a") {}
+    rescue SystemCallError, IOError => e
+      raise LogConfigurationError.new(
+        "cannot open log sink #{@path}: #{e.message}", sink: @path, operation: "open"
+      )
     end
 
+    def rotate_if_needed(next_record_bytes)
+      current_size = File.exist?(@path) ? File.size(@path) : 0
+      return if current_size.zero?
+      return if current_size + next_record_bytes <= @rotate_size
+
+      if @rotate_keep <= 0
+        File.delete(@path)
+        return
+      end
+
+      oldest = "#{@path}.#{@rotate_keep}"
+      File.delete(oldest) if File.exist?(oldest)
+      (@rotate_keep - 1).downto(1) do |n|
+        src = "#{@path}.#{n}"
+        dst = "#{@path}.#{n + 1}"
+        File.rename(src, dst) if File.exist?(src)
+      end
+      File.rename(@path, "#{@path}.1")
+    end
+
+    # 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.
+    def write(encoded_line)
+      clean = encoded_line.gsub(/\e\[[0-9;]*m/, "")
+      payload = clean.b
+
+      acquired = try_lock_with_timeout
+      raise LogWriteError.new("timed out acquiring the log sink lock for #{@path}", sink: @path, operation: "lock") unless acquired
+
+      begin
+        rotate_if_needed(payload.bytesize)
+        File.open(@path, "ab") { |f| f.write(payload) }
+      rescue SystemCallError, IOError => e
+        raise LogWriteError.new("cannot write log sink #{@path}: #{e.message}", sink: @path, operation: "write")
+      ensure
+        @mutex.unlock if @mutex.owned?
+      end
+    end
+
+    def close; end
+
+    private
+
+    def try_lock_with_timeout
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + LOCK_TIMEOUT_SECONDS
+      until @mutex.try_lock
+        return false if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+        sleep(0.005)
+      end
+      true
+    end
+  end
+
+  # Structured logger. 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.
+  #
+  # BREAKING CHANGES from the pre-3.14 logger (this pass, 2026-08-13):
+  #
+  #  * Format defaults to JSON in production and TEXT only when TINA4_DEBUG
+  #    is truthy (Decision 3) -- unchanged in spirit, restated as the shared
+  #    contract's canonical rule.
+  #  * TINA4_LOG_APPEND is REMOVED -- setting it is now a hard configuration
+  #    error.
+  #  * TINA4_LOG_STRICT / TINA4_LOG_FUNC accept ONLY the literal tokens
+  #    "true"/"false" (case-insensitive) -- not "1"/"yes"/"on" (Decision 19:
+  #    "native booleans, not private truth-token parsing").
+  #  * The legacy bracket level spelling ("[TINA4_LOG_ERROR]") is REMOVED --
+  #    it now hard-fails configuration; use the plain name ("ERROR").
+  #  * Embedded CR/LF in a message is now ESCAPED in text format rather than
+  #    passed through raw (Decision 11), and rotation is delegated to a
+  #    hand-written, PREDICTIVE, byte-exact LogFileSink rather than stdlib
+  #    ::Logger (whose backup numbering starts at ".0", not ".1", and whose
+  #    rotation is reactive).
+  #  * New TINA4_LOG_FILE_LEVEL (default ALL) independently gates the FILE
+  #    sink; TINA4_LOG_LEVEL now gates the CONSOLE only (2026-08-10 owner
+  #    override of Decision 8). `enabled?` accepts an optional sink: and is
+  #    sink-aware.
+  #  * `reset` is new: flushes/closes owned sinks and clears the snapshot AND
+  #    the current thread's request id.
+  #  * `close_file_logger` is removed (LOG-A02 prohibits it); `reset` is the
+  #    one lifecycle method now.
+  module Log
+    LEVELS = { "ALL" => 0, "DEBUG" => 1, "INFO" => 2, "WARNING" => 3, "ERROR" => 4, "CRITICAL" => 5, "NONE" => 6 }.freeze
+    DEFAULT_LEVEL = "INFO"
+    DEFAULT_FILE_LEVEL = "ALL"
+    DEFAULT_ROTATE_SIZE = 10 * 1024 * 1024
+    DEFAULT_ROTATE_KEEP = 5
+    MIN_ROTATE_SIZE = 1024
+    STDOUT_MAX_BYTES = 8192
+    OVERFLOW_MESSAGE = "Log event omitted: encoded size exceeds sink limit"
+
+    REMOVED_SETTINGS = {
+      "TINA4_LOG_MAX_SIZE" => "removed setting -- use TINA4_LOG_ROTATE_SIZE (bytes, not megabytes)",
+      "TINA4_LOG_KEEP" => "removed setting -- use TINA4_LOG_ROTATE_KEEP",
+      "TINA4_LOG_APPEND" => "removed setting -- logs always append; truncate explicitly outside logger startup",
+      "TINA4_DEBUG_LEVEL" => "removed setting -- use TINA4_LOG_LEVEL",
+      "TINA4_LOG_CRITICAL" => "removed setting -- critical always emits, subject only to TINA4_LOG_LEVEL"
+    }.freeze
+
+    COLORS = { "DEBUG" => "\e[36m", "INFO" => "\e[32m", "WARNING" => "\e[33m", "ERROR" => "\e[31m", "CRITICAL" => "\e[35m" }.freeze
+    RESET = "\e[0m"
+
+    JSON_KEY_ORDER = %w[timestamp level message request_id function context].freeze
+    CONTROL_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.freeze
+
     class << self
-      attr_reader :log_dir, :log_file_path
+      # ── configuration ──────────────────────────────────────────────
 
-      # configure(target = nil)
-      #
-      # 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)
-      #   TINA4_LOG_DIR=log                    -> ./log/
+      # Resolve and activate a new configuration snapshot.
       #
-      # A target with a file extension is a file path; anything else is a
-      # directory (an existing directory is always treated as one, extension or
-      # not). Naming a file means "one file at this path", so no error.log
-      # appears beside it -- same rule TINA4_LOG_FILE already followed.
-      #
-      # BREAKING for Ruby callers: the argument used to be a project ROOT with
-      # `logs/` appended, so `configure("/app")` wrote to /app/logs/ while the
-      # identical call on Python and PHP wrote to /app/. That is the same
-      # file-versus-directory confusion feature 1 found in loadEnv, and it made
-      # "put the logs exactly here" impossible to express. If you relied on the
-      # old behaviour, pass the parent explicitly: `configure(File.join(root, "logs"))`.
-      def configure(target = nil)
-        # Explicit argument wins, then TINA4_LOG_DIR, then ./logs.
-        log_dir_env = ENV["TINA4_LOG_DIR"]
-        log_dir_env = nil if log_dir_env && log_dir_env.empty?
-        chosen = target || log_dir_env || "logs"
-        chosen = File.join(Dir.pwd, chosen) unless File.absolute_path?(chosen)
-
-        if target_is_file?(chosen)
-          @log_dir = File.dirname(chosen)
-          explicit_target_file = chosen
+      # Precedence for every field (ADR-0041): explicit argument, then the
+      # matching TINA4_LOG_* environment value, then the built-in default.
+      # Every field is validated BEFORE any directory is created or file is
+      # opened; a failed reconfiguration leaves the prior snapshot untouched.
+      def configure(log_dir: nil, log_file: nil, level: nil, file_level: nil, format: nil,
+                     output: nil, rotate_size: nil, rotate_keep: nil, strict: nil, caller_capture: nil)
+        REMOVED_SETTINGS.each do |name, hint|
+          raise LogConfigurationError.new("#{name} is a removed setting -- #{hint}", setting: name, value: ENV[name]) if ENV.key?(name)
+        end
+
+        resolved_level = resolve_level(level, "TINA4_LOG_LEVEL", DEFAULT_LEVEL)
+        resolved_file_level = resolve_level(file_level, "TINA4_LOG_FILE_LEVEL", DEFAULT_FILE_LEVEL)
+        resolved_format = resolve_format(format)
+        stdout_enabled, file_enabled = resolve_output(output)
+        resolved_rotate_size = resolve_int(rotate_size, "TINA4_LOG_ROTATE_SIZE", DEFAULT_ROTATE_SIZE, MIN_ROTATE_SIZE)
+        resolved_rotate_keep = resolve_int(rotate_keep, "TINA4_LOG_ROTATE_KEEP", DEFAULT_ROTATE_KEEP, 0)
+        resolved_strict = resolve_bool(strict, "TINA4_LOG_STRICT", false)
+        resolved_caller = resolve_bool(caller_capture, "TINA4_LOG_FUNC", false)
+
+        dir_raw = resolve_str(log_dir, "TINA4_LOG_DIR", "logs", allow_empty: false)
+        file_raw = resolve_str(log_file, "TINA4_LOG_FILE", nil, allow_empty: true)
+
+        project_root = Dir.pwd
+        dir_candidate = dir_raw
+        file_candidate = file_raw
+        if file_candidate.nil? && target_is_file?(dir_candidate)
+          file_candidate = File.basename(dir_candidate)
+          dir_candidate = File.dirname(dir_candidate)
+        end
+
+        resolved_log_dir = File.absolute_path?(dir_candidate) ? dir_candidate : File.join(project_root, dir_candidate)
+        resolved_log_dir = resolved_log_dir.chomp("/")
+
+        if file_candidate && !file_candidate.empty?
+          resolved_log_file = File.absolute_path?(file_candidate) ? file_candidate : File.join(resolved_log_dir, file_candidate)
+          layout = "single"
         else
-          @log_dir = chosen
-          explicit_target_file = nil
+          resolved_log_file = nil
+          layout = "directory"
         end
-        FileUtils.mkdir_p(@log_dir)
-
-        # A file path passed to configure() wins, then TINA4_LOG_FILE (absolute
-        # or relative to log_dir). Default: <log_dir>/tina4.log.
-        log_file_env = ENV["TINA4_LOG_FILE"]
-        log_file_env = nil if log_file_env && log_file_env.empty?
-        @log_file_path = if explicit_target_file
-                           explicit_target_file
-                         elsif log_file_env
-                           File.absolute_path?(log_file_env) ? log_file_env : File.join(@log_dir, log_file_env)
-                         else
-                           File.join(@log_dir, "tina4.log")
-                         end
-
-        # TINA4_LOG_ROTATE_SIZE — bytes per file before rotation. 0 = no rotation.
-        @rotate_size = (ENV["TINA4_LOG_ROTATE_SIZE"] || DEFAULT_ROTATE_SIZE).to_i
-        # TINA4_LOG_ROTATE_KEEP — number of rotated backups to keep.
-        @rotate_keep = (ENV["TINA4_LOG_ROTATE_KEEP"] || DEFAULT_ROTATE_KEEP).to_i
-
-        # TINA4_LOG_FORMAT — "text" or "json". TEXT IS THE DEFAULT, always.
-        #
-        # Owner decision 2026-08-01: nothing but an explicit TINA4_LOG_FORMAT=json
-        # selects JSON. The implicit "production means JSON" switch is DELETED in
-        # all four frameworks, because MEASURED, "production" meant four different
-        # things and it silently picked your log format:
-        #
-        #   node   !isTruthy(TINA4_DEBUG)                     -> JSON with TINA4_DEBUG unset
-        #   ruby   TINA4_ENV|RACK_ENV|RUBY_ENV == "production"
-        #   python only via configure(production=True)
-        #   php    no switch at all — JSON was the shipped default
-        #
-        # Same machine, same .env, four formats. An OBJECT (Hash/Array) passed as
-        # the message is still JSON-encoded INLINE inside the text line — that is
-        # coerce_message's job and it is unchanged.
-        format_env = ENV["TINA4_LOG_FORMAT"]
-        @format = format_env && !format_env.empty? ? format_env.downcase : "text"
-        @json_mode = @format == "json"
-
-        # TINA4_LOG_OUTPUT — "stdout", "file", or "both".
-        #
-        # Default (UNSET): stdout is ALWAYS on. The log FILE (tina4.log + any
-        # error log) is written ONLY in development — i.e. when TINA4_DEBUG is
-        # truthy. In production / containers (TINA4_DEBUG falsy) the logger is
-        # stdout-only: writing a log file inside a container just bloats the
-        # writable layer + disk, and 12-factor wants logs on stdout for the
-        # platform to capture. An explicit TINA4_LOG_OUTPUT=file/both (or an
-        # explicit TINA4_LOG_FILE path) overrides this and STILL writes a file.
-        # Mirrors the Python master (debug/__init__.py configure()).
-        # An explicit TINA4_LOG_FILE always wins: a path the operator named must
-        # be written even in production (parity with the Python master, where an
-        # explicit log_file builds a writer unconditionally), so the dev-gated
-        # default below resolves to "both" (stdout + file) rather than "stdout".
-        # "The operator named ONE file" — via TINA4_LOG_FILE or by passing a file
-        # path to configure(). Either way a file must be written even in
-        # production, and no error.log sibling appears next to it.
-        explicit_file = !log_file_env.nil? || !explicit_target_file.nil?
-        default_output = if explicit_file || truthy?(ENV["TINA4_DEBUG"])
-                           "both"
-                         else
-                           "stdout"
-                         end
-        output_env = ENV["TINA4_LOG_OUTPUT"]
-        @output = if output_env && !output_env.empty?
-                    output_env.downcase
-                  else
-                    default_output
-                  end
-        @output = default_output unless %w[stdout file both].include?(@output)
-
-        # TINA4_LOG_STRICT — when true, raise on log write failures instead of swallowing.
-        @strict = truthy?(ENV["TINA4_LOG_STRICT"])
-
-        @console_level = resolve_level
-        @request_id = nil
-        @current_context = {}
-        @mutex = Mutex.new
 
-        # v3.13.14: unbuffer stdout so logs reach `docker logs` / k8s
-        # immediately. A non-TTY $stdout (every container) is block-buffered
-        # by default — logs sat in the buffer until it filled or the process
-        # exited, so operators "weren't getting logs". No-op when output is
-        # file-only.
-        $stdout.sync = true if @output != "file"
-
-        # Build the file logger via stdlib Logger which handles rotation natively.
-        # Logger.new(path, shift_age, shift_size):
-        #   shift_age  = number of files to keep
-        #   shift_size = bytes before rotation
-        # When @rotate_size is 0, omit rotation args.
-        close_file_logger
-
-        # TINA4_LOG_APPEND — append (default) or overwrite on startup.
-        #
-        # APPEND IS THE DEFAULT: a log you can lose by restarting the process is
-        # not a log. Set it false when you want one file per run (a short CLI, a
-        # test fixture, a container that ships logs elsewhere) and the file is
-        # truncated once here at configure time, never per line.
-        @append = ENV["TINA4_LOG_APPEND"].nil? || truthy?(ENV["TINA4_LOG_APPEND"])
-
-        if @output != "stdout"
-          unless @append
-            [@log_file_path, File.join(@log_dir, "error.log")].each do |path|
-              File.write(path, "") if File.exist?(path)
-            end
+        output_selector = if stdout_enabled && file_enabled
+                             "both"
+                           else
+                             file_enabled ? "file" : "stdout"
+                           end
+
+        snap = {
+          level: resolved_level, file_level: resolved_file_level, format: resolved_format,
+          output: output_selector, log_dir: resolved_log_dir, log_file: resolved_log_file,
+          layout: layout, rotate_size: resolved_rotate_size, rotate_keep: resolved_rotate_keep,
+          strict: resolved_strict, caller_capture: resolved_caller,
+          stdout_enabled: stdout_enabled, file_enabled: file_enabled,
+          main_sink: nil, error_sink: nil
+        }
+
+        if file_enabled
+          if layout == "single"
+            sink = LogFileSink.new(resolved_log_file, resolved_rotate_size, resolved_rotate_keep)
+            sink.open
+            snap[:main_sink] = sink
+          else
+            main_sink = LogFileSink.new(File.join(resolved_log_dir, "tina4.log"), resolved_rotate_size, resolved_rotate_keep)
+            main_sink.open
+            error_sink = LogFileSink.new(File.join(resolved_log_dir, "error.log"), resolved_rotate_size, resolved_rotate_keep)
+            error_sink.open
+            snap[:main_sink] = main_sink
+            snap[:error_sink] = error_sink
           end
-          @file_logger = build_file_logger(@log_file_path)
-
-          # Mirror WARNING and above into a dedicated error.log so
-          # `tail -f logs/error.log` gives just the stuff worth looking at.
-          # Ruby 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 an explicit TINA4_LOG_FILE:
-          # they asked for one file at one path, so a sibling error.log
-          # appearing next to it would be a surprise.
-          @error_logger = if explicit_file
-                            nil
-                          else
-                            build_file_logger(File.join(@log_dir, "error.log"))
-                          end
         end
 
-        @initialized = true
+        # v3.13.14: unbuffer stdout so logs reach `docker logs` / k8s
+        # immediately -- a non-TTY $stdout (every container) is
+        # block-buffered by default, so lines sat in the buffer until it
+        # filled or the process exited.
+        $stdout.sync = true if stdout_enabled
+
+        @snapshot = snap
+        @pid = Process.pid
+        nil
       end
 
-      def set_request_id(id)
-        @mutex.synchronize { @request_id = id }
+      # Flush/close owned sinks, clear the snapshot and the current thread's
+      # request id. Idempotent; the next use resolves a fresh snapshot.
+      def reset
+        @snapshot = nil
+        Thread.current[:tina4_request_id] = nil
+        nil
       end
 
-      def clear_request_id
-        @mutex.synchronize { @request_id = nil }
+      # A defensive native-map copy of the effective, stable configuration.
+      def configuration
+        snap = ensure_snapshot
+        {
+          "level" => snap[:level], "file_level" => snap[:file_level], "format" => snap[:format],
+          "output" => snap[:output], "log_dir" => snap[:log_dir], "log_file" => snap[:log_file],
+          "layout" => snap[:layout], "rotate_size" => snap[:rotate_size], "rotate_keep" => snap[:rotate_keep],
+          "strict" => snap[:strict], "caller" => snap[:caller_capture],
+          "stdout_enabled" => snap[:stdout_enabled], "file_enabled" => snap[:file_enabled]
+        }
+      end
+
+      # ── request id (thread-local; Decision 12) ───────────────────────
+
+      def set_request_id(request_id)
+        discard_state_if_forked
+        Thread.current[:tina4_request_id] = request_id
       end
 
       def get_request_id
-        @mutex.synchronize { @request_id }
+        discard_state_if_forked
+        Thread.current[:tina4_request_id]
       end
 
-      def json_mode?
-        @json_mode
+      def clear_request_id
+        Thread.current[:tina4_request_id] = nil
       end
 
-      # Would a message at `level` pass the configured MINIMUM CONSOLE LEVEL
-      # (TINA4_LOG_LEVEL)? Returns true iff `log` would print it to stdout —
-      # it reflects CONSOLE visibility only. The log FILE records every level
-      # regardless of this threshold, so this never gates file output.
-      #
-      # `level` accepts a String or Symbol and is case-insensitive
-      # ("INFO", :info, "Warning", :warning all work). Mirrors Python's
-      # Log.is_enabled. It REUSES the exact severity >= @console_level
-      # comparison the console branch in `log` uses (line ~167) via
-      # SEVERITY_MAP / resolve_level — it never re-implements level
-      # comparison, so it can never disagree with what the logger prints.
-      #
-      # "critical" is a FIRST-CLASS top-level severity (4 — above error 3),
-      # not a parity alias for error. It is evaluated with ordinary threshold
-      # logic (critical 4 >= @console_level), so it passes at every level
-      # except none (5) — matching the Python master.
-      def enabled?(level)
-        sym = normalize_level(level)
-        severity = SEVERITY_MAP[sym] || 0
-        severity >= console_level
+      def sanitize_request_id(value)
+        return nil if value.nil? || value.empty?
+        return nil if value.length > 128
+        return nil if value =~ /[^A-Za-z0-9._-]/
+
+        value
       end
 
-      def info(message, context = {})
-        log(:info, message, context)
+      # ── threshold ─────────────────────────────────────────────────
+
+      # True when `level` passes the queried sink's threshold and that sink
+      # is active. `sink:` is nil (console, the historical meaning),
+      # :console/"console"/:stdout/"stdout", or :file/"file".
+      def enabled?(level, sink: nil)
+        raise LogArgumentError.new("enabled? requires a level", argument: "level") if level.nil?
+
+        key = level.to_s.strip.upcase
+        raise LogArgumentError.new("#{level.inspect} is not a valid level", argument: "level", accepted: LEVELS.keys) unless LEVELS.key?(key)
+
+        snap = ensure_snapshot
+        sink_key = sink.nil? ? nil : sink.to_s
+        case sink_key
+        when nil, "console", "stdout"
+          snap[:stdout_enabled] && LEVELS[key] >= LEVELS[snap[:level]]
+        when "file"
+          snap[:file_enabled] && LEVELS[key] >= LEVELS[snap[:file_level]]
+        else
+          raise LogArgumentError.new("#{sink.inspect} is not a valid sink", argument: "sink", accepted: %w[console file])
+        end
       end
 
+      # ── event methods (Decision 23, section 5) ───────────────────────
+
       def debug(message, context = {})
-        log(:debug, message, context)
+        emit("DEBUG", message, context)
+      end
+
+      def info(message, context = {})
+        emit("INFO", message, context)
       end
 
       def warning(message, context = {})
-        log(:warn, message, context)
+        emit("WARNING", message, context)
       end
 
       def error(message, context = {})
-        log(:error, message, context)
+        emit("ERROR", message, context)
       end
 
-      # critical is the HIGHEST severity (4, above error). Like every other
-      # level it ALWAYS emits, subject only to the TINA4_LOG_LEVEL threshold
-      # (which critical passes at every level except none). A critical log is
-      # never a silent no-op. Mirrors the Python master.
+      # Critical -- the highest severity. Always emitted, subject only to
+      # the configured threshold.
       def critical(message, context = {})
-        log(:critical, message, context)
+        emit("CRITICAL", message, context)
       end
 
-      # Test/teardown helper — closes the underlying Logger so the file
-      # handle is released (Windows / tmpdir cleanup).
-      def close_file_logger
-        @file_logger&.close rescue nil
-        @file_logger = nil
-        @error_logger&.close rescue nil
-        @error_logger = nil
+      private
+
+      def emit(level, message, context)
+        snap = ensure_snapshot
+        console_ok = snap[:stdout_enabled] && LEVELS[level] >= LEVELS[snap[:level]]
+        file_ok = snap[:file_enabled] && LEVELS[level] >= LEVELS[snap[:file_level]]
+        return unless console_ok || file_ok
+
+        request_id = Thread.current[:tina4_request_id]
+        caller_name = snap[:caller_capture] ? resolve_caller_name : nil
+        event = build_event(level, message, request_id, caller_name, context)
+
+        if console_ok
+          stdout_line = bounded_for_sink(event, snap[:format], STDOUT_MAX_BYTES).chomp("\n")
+          plain = snap[:format] == "json" || !stdout_tty?
+          color = plain ? "" : (COLORS[level] || "")
+          reset_code = plain ? "" : RESET
+          write_stdout("#{color}#{stdout_line}#{reset_code}\n")
+        end
+
+        if file_ok && snap[:main_sink]
+          main_line = bounded_for_sink(event, snap[:format], snap[:rotate_size])
+          write_sink(snap[:main_sink], main_line, snap[:strict])
+          if snap[:layout] == "directory" && snap[:error_sink] && LEVELS[level] >= LEVELS["WARNING"]
+            write_sink(snap[:error_sink], main_line, snap[:strict])
+          end
+        end
+        nil
       end
 
-      private
+      def write_stdout(line)
+        $stdout.write(line)
+        $stdout.flush
+      end
+
+      def write_sink(sink, line, strict)
+        sink.write(line)
+      rescue LogWriteError => e
+        raise e if strict
 
-      def truthy?(val)
-        Tina4::Env.is_truthy(val)
+        write_stdout("tina4: log sink #{sink.path} failed: #{e.message}\n")
       end
 
-      def log(level, message, context = {})
-        configure unless @initialized
-        @current_context = context.is_a?(Hash) ? context : {}
+      def stdout_tty?
+        $stdout.respond_to?(:tty?) && $stdout.tty?
+      end
 
-        # Coerce FIRST. Anything can arrive as a message: a Hash from a handler,
-        # a binary payload off a socket, a 10MB string. See coerce_message.
-        message = coerce_message(message)
-        formatted = format_line(level, message)
+      # ── caller capture (Decision 16) ─────────────────────────────────
 
-        # Console output respects TINA4_LOG_LEVEL and TINA4_LOG_OUTPUT
-        severity = SEVERITY_MAP[level] || 0
-        if severity >= @console_level && @output != "file"
-          # Truncate on the CONSOLE only. The file keeps the full line so a
-          # consumer parsing it loses nothing; a terminal does not need 10MB.
-          if @json_mode
-            $stdout.puts truncate_for_stdout(json_line(level, message))
-          else
-            $stdout.puts colorize(level, truncate_for_stdout(formatted))
-          end
-        end
+      OWN_FRAMES = %w[resolve_caller_name build_event emit debug info warning error critical].freeze
+      NOISE_FRAME_RE = /\A(?:block(?: \(\d+ levels\))? in |<top \(required\)>|<main>)/.freeze
+
+      def resolve_caller_name
+        locs = caller_locations(2, 16) || []
+        locs.each do |loc|
+          label = loc.base_label.to_s
+          next if OWN_FRAMES.include?(label)
+          next if label.empty? || NOISE_FRAME_RE.match?(label)
 
-        # File output — always full level (consumer parses themselves) — unless disabled.
-        if @output != "stdout" && @file_logger
-          payload = @json_mode ? json_line(level, message) : strip_ansi(formatted)
-          write_to_file(payload, level)
+          return label
         end
+        nil
+      rescue StandardError
+        nil
+      end
 
-        @current_context = {}
+      # ── native normalization (Decision 14, section 6) ────────────────
+
+      def normalize(value, ancestors = [])
+        return value if value.nil? || value == true || value == false
+
+        case value
+        when String
+          decode_maybe_binary(value)
+        when Integer
+          value
+        when Float
+          value.finite? ? value : "[Unsupported]"
+        when Array
+          return "[Circular]" if ancestors.any? { |a| a.equal?(value) }
+
+          nxt = ancestors + [value]
+          value.map { |v| normalize(v, nxt) }
+        when Hash
+          return "[Circular]" if ancestors.any? { |a| a.equal?(value) }
+
+          nxt = ancestors + [value]
+          out = {}
+          value.each { |k, v| out[k.to_s] = normalize(v, nxt) }
+          out
+        else
+          "[Unsupported]"
+        end
       end
 
-      # The current minimum console level as an integer (the same value
-      # the console branch in `log` compares against). Ensures the logger
-      # is configured so `enabled?` works before any log call has run.
-      def console_level
-        configure unless @initialized
-        @console_level
+      def decode_maybe_binary(str)
+        return str if str.encoding == Encoding::UTF_8 && str.valid_encoding?
+
+        utf8 = str.dup.force_encoding(Encoding::UTF_8)
+        return utf8 if utf8.valid_encoding?
+
+        "<binary #{str.bytesize} bytes sha256=#{Digest::SHA256.hexdigest(str)}>"
       end
 
-      # Map a level (String or Symbol, case-insensitive) onto the symbol
-      # space used by SEVERITY_MAP. Accepts the public method names
-      # (debug/info/warning/error/critical) and the internal :warn symbol.
-      # critical is a FIRST-CLASS level (severity 4), not an alias for error.
-      # Unknown levels fall through to their own symbol and resolve to
-      # severity 0 in `enabled?`.
-      def normalize_level(level)
-        sym = level.to_s.strip.downcase.to_sym
-        case sym
-        when :warning then :warn
-        else sym
+      def sort_keys_recursive(value)
+        case value
+        when Hash
+          value.keys.sort.each_with_object({}) { |k, out| out[k] = sort_keys_recursive(value[k]) }
+        when Array
+          value.map { |v| sort_keys_recursive(v) }
+        else
+          value
         end
       end
 
-      def resolve_level
-        # v3.13.14: default is INFO (was ALL) so a deployed app surfaces
-        # request/startup/warn/error without debug noise, matching
-        # Python/PHP/Node. Accept BOTH the legacy bracket form
-        # ("[TINA4_LOG_ERROR]") AND plain names ("ERROR") so the env value
-        # is portable across all four frameworks.
-        raw = (ENV["TINA4_LOG_LEVEL"] || "").strip
-        return 1 if raw.empty? # INFO
-        key = raw.start_with?("[") ? raw.upcase : "[TINA4_LOG_#{raw.upcase}]"
-        LEVELS[key] || 1
-      end
-
-      def severity_to_level(level)
-        case level
-        when :debug then "DEBUG"
-        when :info  then "INFO"
-        when :warn  then "WARNING"
-        when :error then "ERROR"
-        when :critical then "CRITICAL"
-        else level.to_s.upcase
+      def compact_json(value)
+        JSON.generate(value)
+      end
+
+      # The top-level `message` field: a string passes through; anything
+      # else uses compact, key-sorted JSON spelling (Decision 14).
+      def message_to_string(raw)
+        return decode_maybe_binary(raw) if raw.is_a?(String)
+
+        normalized = normalize(raw)
+        return "null" if normalized.nil?
+        return "true" if normalized == true
+        return "false" if normalized == false
+        return JSON.generate(normalized) if normalized.is_a?(Numeric)
+        return compact_json(sort_keys_recursive(normalized)) if normalized.is_a?(Array) || normalized.is_a?(Hash)
+
+        normalized.to_s # already a marker string
+      end
+
+      # Escape backslash, CR, LF (in that order) and strip other C0/DEL so a
+      # text-format record is exactly one physical LF-terminated line
+      # (Decision 11).
+      ESCAPE_CHARS = /[\\\r\n]/.freeze
+
+      # Escape backslash, CR, LF and strip other C0/DEL so a text-format
+      # record is exactly one physical LF-terminated line (Decision 11). A
+      # single combined regex + BLOCK replacement (not a string replacement
+      # -- String#gsub treats "\\"/"\1" etc. in a string replacement
+      # specially, which is exactly the kind of double-escaping bug this
+      # needs to avoid) walks the original string once, so a
+      # newly-introduced backslash from escaping \r or \n is never
+      # re-scanned or double-escaped.
+      def escape_text(str)
+        out = str.gsub(ESCAPE_CHARS) do |c|
+          case c
+          when "\\" then '\\\\'
+          when "\r" then '\r'
+          when "\n" then '\n'
+          end
         end
+        out.gsub(CONTROL_CHARS, "")
       end
 
-      def utc_timestamp
+      # ── canonical event + encoding (Decision 15) ─────────────────────
+
+      def timestamp_now
         now = Time.now.utc
         now.strftime("%Y-%m-%dT%H:%M:%S.") + format("%03d", now.usec / 1000) + "Z"
       end
 
-      def strip_ansi(text)
-        text.gsub(ANSI_RE, "")
+      def build_event(level, message, request_id, caller_name, context)
+        event = { "timestamp" => timestamp_now, "level" => level, "message" => message_to_string(message) }
+        event["request_id"] = request_id if request_id && !request_id.empty?
+        event["function"] = caller_name if caller_name && !caller_name.empty?
+        if context && !context.empty?
+          normalized_ctx = sort_keys_recursive(normalize(context))
+          event["context"] = normalized_ctx if normalized_ctx && !normalized_ctx.empty?
+        end
+        event
       end
 
-      def format_line(level, message)
-        level_str = severity_to_level(level)
-        ts = utc_timestamp
-        rid = get_request_id
-        rid_str = rid ? " [#{rid}]" : ""
-        fn = caller_name
-        fn_str = fn ? " [#{fn}]" : ""
-        ctx = @current_context && !@current_context.empty? ? " #{JSON.generate(@current_context)}" : ""
-        # Pad to 8, not 7: CRITICAL is eight characters, so a 7-wide column was
-        # broken by our own highest level. 8 is the only width that fits every
-        # level name. Cross-framework format table (feature 2 of the audit).
-        "#{ts} [#{level_str.ljust(8)}]#{rid_str}#{fn_str} #{message}#{ctx}"
+      def encode_json(event)
+        ordered = {}
+        JSON_KEY_ORDER.each { |k| ordered[k] = event[k] if event.key?(k) }
+        "#{compact_json(ordered)}\n"
       end
 
-      def json_line(level, message)
-        level_str = severity_to_level(level)
-        entry = {
-          timestamp: utc_timestamp,
-          level: level_str,
-          message: message
+      def encode_text(event)
+        parts = [event["timestamp"], "[#{event['level'].ljust(8)}]"]
+        parts << "[#{event['request_id']}]" if event.key?("request_id")
+        parts << "[#{event['function']}]" if event.key?("function")
+        parts << escape_text(event["message"])
+        parts << compact_json(event["context"]) if event.key?("context")
+        "#{parts.join(' ')}\n"
+      end
+
+      def encode(event, fmt)
+        fmt == "json" ? encode_json(event) : encode_text(event)
+      end
+
+      def overflow_record(original_event, original_encoded, fmt)
+        original_bytes = original_encoded.b
+        replacement = {
+          "timestamp" => original_event["timestamp"], "level" => original_event["level"],
+          "message" => OVERFLOW_MESSAGE,
+          "context" => { "truncated" => true, "original_bytes" => original_bytes.bytesize, "sha256" => Digest::SHA256.hexdigest(original_bytes) }
         }
-        rid = get_request_id
-        entry[:request_id] = rid if rid
-        fn = caller_name
-        entry[:function] = fn if fn
-        entry[:context] = @current_context if @current_context && !@current_context.empty?
-        JSON.generate(entry)
-      end
-
-      # Names that belong to Log itself — walk past them so the reported
-      # frame is the real caller (e.g. the route handler or service
-      # method that called Log.info). Kept as a Set for O(1) lookup.
-      OWN_FRAMES = %w[
-        caller_name format_line json_line log colorize write_to_file
-        debug info warning error critical
-      ].freeze
-
-      # Names that are noise — Ruby block labels, lambdas, top-level
-      # script frames. We skip these the same way Python skips <module>
-      # and <lambda>.
-      NOISE_FRAME_RE = /\A(?:block(?: \(\d+ levels\))? in |<top \(required\)>|<main>)/
-
-      # Return the name of the function that called Log.{debug,info,warning,error}.
-      # Active only when TINA4_LOG_FUNC=true (parity feature #41).
-      # Returns nil on any error so it never crashes a log call.
-      def caller_name
-        return nil unless Tina4::Env.bool("TINA4_LOG_FUNC")
-
-        # caller_locations(2, 16) skips this method + log() and gives us
-        # up to 16 frames to walk. We bail out the moment we hit a frame
-        # whose base_label isn't in OWN_FRAMES and isn't a block label.
-        locs = caller_locations(2, 16) || []
-        locs.each do |loc|
-          label = loc.base_label.to_s
-          next if OWN_FRAMES.include?(label)
-          next if label.empty? || NOISE_FRAME_RE.match?(label)
-          return label
+        encode(replacement, fmt)
+      end
+
+      def bounded_for_sink(event, fmt, max_bytes)
+        encoded = encode(event, fmt)
+        return encoded if encoded.b.bytesize <= max_bytes
+
+        overflow_record(event, encoded, fmt)
+      end
+
+      # ── resolution helpers ────────────────────────────────────────
+
+      # Delegates to the ONE shared env-truthiness table (Tina4::Env.is_truthy)
+      # rather than a private list of its own. Log used to keep its own
+      # y/t-inclusive list here, which is the EXACT historical bug
+      # spec/dotenv_corpus_spec.rb exists to catch: TINA4_LOG_FUNC=y switched
+      # function logging ON while TINA4_DEBUG=y left debug OFF, in the same
+      # process, because two subsystems answered "is this truthy" two
+      # different ways from the same .env.
+      def truthy?(value)
+        Tina4::Env.is_truthy(value)
+      end
+
+      def truthy_debug?
+        truthy?(ENV["TINA4_DEBUG"])
+      end
+
+      def parse_bool_setting(name, default)
+        return default unless ENV.key?(name)
+
+        token = ENV[name].strip.downcase
+        return true if token == "true"
+        return false if token == "false"
+
+        raise LogConfigurationError.new(
+          "#{name}=#{ENV[name].inspect} is not a valid boolean; accepted: true, false",
+          setting: name, value: ENV[name], accepted: %w[true false]
+        )
+      end
+
+      def resolve_bool(explicit, env_name, default)
+        return explicit unless explicit.nil?
+
+        parse_bool_setting(env_name, default)
+      end
+
+      def resolve_level(explicit, env_name, default)
+        if !explicit.nil?
+          candidate = explicit.to_s
+          source = "argument"
+        elsif ENV.key?(env_name)
+          candidate = ENV[env_name]
+          source = env_name
+        else
+          return default
         end
-        nil
-      rescue StandardError
-        nil
+        key = candidate.strip.upcase
+        unless LEVELS.key?(key)
+          raise LogConfigurationError.new(
+            "#{source}=#{candidate.inspect} is not a valid level; accepted: #{LEVELS.keys}",
+            setting: env_name, value: candidate, accepted: LEVELS.keys
+          )
+        end
+        key
+      end
+
+      def resolve_format(explicit)
+        if !explicit.nil?
+          candidate = explicit.to_s.strip.downcase
+          unless %w[text json].include?(candidate)
+            raise LogConfigurationError.new("format=#{explicit.inspect} is not valid; accepted: text, json", setting: "TINA4_LOG_FORMAT", value: explicit, accepted: %w[text json])
+          end
+          return candidate
+        end
+        if ENV.key?("TINA4_LOG_FORMAT")
+          candidate = ENV["TINA4_LOG_FORMAT"].strip.downcase
+          unless %w[text json].include?(candidate)
+            raise LogConfigurationError.new("TINA4_LOG_FORMAT=#{ENV['TINA4_LOG_FORMAT'].inspect} is not valid; accepted: text, json", setting: "TINA4_LOG_FORMAT", value: ENV["TINA4_LOG_FORMAT"], accepted: %w[text json])
+          end
+          return candidate
+        end
+        truthy_debug? ? "text" : "json"
       end
 
-      def colorize(level, line)
-        color = case level
-                when :debug   then COLORS[:cyan]
-                when :info    then COLORS[:green]
-                when :warn    then COLORS[:yellow]
-                when :error   then COLORS[:red]
-                when :critical then COLORS[:magenta]
-                else COLORS[:reset]
-                end
-        "#{color}#{line}#{COLORS[:reset]}"
+      def resolve_output(explicit)
+        if !explicit.nil?
+          candidate = explicit.to_s.strip.downcase
+          source = "argument"
+        elsif ENV.key?("TINA4_LOG_OUTPUT")
+          candidate = ENV["TINA4_LOG_OUTPUT"].strip.downcase
+          source = "TINA4_LOG_OUTPUT"
+        else
+          return [true, truthy_debug?]
+        end
+        unless %w[stdout file both].include?(candidate)
+          raise LogConfigurationError.new("#{source}=#{candidate.inspect} is not valid; accepted: stdout, file, both", setting: "TINA4_LOG_OUTPUT", value: candidate, accepted: %w[stdout file both])
+        end
+        case candidate
+        when "stdout" then [true, false]
+        when "file" then [false, true]
+        when "both" then [true, true]
+        end
+      end
+
+      def resolve_int(explicit, env_name, default, minimum)
+        if !explicit.nil?
+          raise LogConfigurationError.new("#{env_name}=#{explicit.inspect} is not a valid integer", setting: env_name, value: explicit) unless explicit.is_a?(Integer)
+
+          value = explicit
+          source = "argument"
+        elsif ENV.key?(env_name)
+          raw = ENV[env_name]
+          unless raw.strip =~ /\A-?\d+\z/
+            raise LogConfigurationError.new("#{env_name}=#{raw.inspect} is not a valid integer", setting: env_name, value: raw)
+          end
+          value = raw.to_i
+          source = env_name
+        else
+          return default
+        end
+        if !minimum.nil? && value < minimum
+          raise LogConfigurationError.new("#{source}=#{value} must be >= #{minimum}", setting: env_name, value: value, accepted: ">= #{minimum}")
+        end
+        value
+      end
+
+      def resolve_str(explicit, env_name, default, allow_empty:)
+        if !explicit.nil?
+          raise LogConfigurationError.new("#{env_name} may not be an empty string", setting: env_name, value: explicit) if explicit.empty?
+          raise LogConfigurationError.new("#{env_name} may not contain a NUL byte", setting: env_name, value: explicit) if explicit.include?("\0")
+
+          return explicit
+        end
+        return default unless ENV.key?(env_name)
+
+        raw = ENV[env_name]
+        if raw.empty?
+          raise LogConfigurationError.new("#{env_name} may not be an empty string", setting: env_name, value: raw) unless allow_empty
+
+          return default
+        end
+        raise LogConfigurationError.new("#{env_name} may not contain a NUL byte", setting: env_name, value: raw) if raw.include?("\0")
+
+        raw
       end
 
-      # Build one rotating file logger. stdlib Logger handles rotation natively:
-      #   Logger.new(path, shift_age, shift_size)  — files to keep, bytes before roll.
-      # With @rotate_size 0 the rotation args are omitted. tina4.log and error.log
-      # each get their own logger so they rotate independently.
-      # Turn anything into a single safe line of text.
-      #
-      # A String passes through when it is valid UTF-8. Binary is described
-      # rather than dumped: raw bytes at a terminal garble it and can emit
-      # escape sequences. Anything else becomes JSON, because a Hash rendered as
-      # text is the whole reason the caller logged it, falling back to inspect
-      # for a value JSON cannot represent. The logger must never be the reason a
-      # request dies.
-      def coerce_message(message)
-        text = case message
-               when String
-                 if message.encoding == Encoding::BINARY || !message.valid_encoding?
-                   utf8 = message.dup.force_encoding(Encoding::UTF_8)
-                   return "<binary #{message.bytesize} bytes>" unless utf8.valid_encoding?
-                   utf8
-                 else
-                   message
-                 end
-               when Hash, Array
-                 begin
-                   JSON.generate(message)
-                 rescue StandardError
-                   message.inspect
-                 end
-               when nil
-                 ""
-               else
-                 message.respond_to?(:to_s) ? message.to_s : message.inspect
-               end
-        text.gsub(CONTROL_CHARS, "")
-      end
-
-      def truncate_for_stdout(line)
-        return line if line.length <= STDOUT_MAX_CHARS
-        "#{line[0, STDOUT_MAX_CHARS]}... (truncated, #{line.length} chars)"
-      end
-
-      # 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
-      # needing the path to exist yet.
       def target_is_file?(path)
         return false if File.directory?(path)
-        File.extname(path) != ""
-      end
-
-      def build_file_logger(path)
-        # In strict mode ask ::Logger to let a real write error through instead
-        # of warning on stderr and returning (see STRICT_WRITE_ERRORS). Empty
-        # otherwise, which is the stdlib default, so the non-strict path behaves
-        # byte for byte as it always has.
-        reraise = @strict ? STRICT_WRITE_ERRORS : []
-        # HeaderlessLogDevice, not a bare path: ::Logger would otherwise open the
-        # file with a "# Logfile created on ..." banner that is not a log line
-        # (and not JSON). It still does the rotation — shift_age = files kept,
-        # shift_size = bytes before a roll; with @rotate_size 0 both are omitted
-        # so rotation is off. reraise_write_errors is passed to BOTH layers or
-        # the outer one swallows what the inner one raises (see STRICT_WRITE_ERRORS).
-        device = if @rotate_size > 0
-                   HeaderlessLogDevice.new(path, shift_age: @rotate_keep,
-                                           shift_size: @rotate_size,
-                                           reraise_write_errors: reraise)
-                 else
-                   HeaderlessLogDevice.new(path, reraise_write_errors: reraise)
-                 end
-        logger = ::Logger.new(device, reraise_write_errors: reraise)
-        # We do our own formatting — strip Logger's default formatter.
-        logger.formatter = proc { |_sev, _t, _p, msg| msg.to_s.end_with?("\n") ? msg : "#{msg}\n" }
-        logger
-      end
-
-      def write_to_file(line, level = nil)
-        return unless @file_logger
-        # Use << to bypass Logger's severity filtering — we already filtered above.
-        @file_logger << "#{line}\n"
-        # WARNING and above only. Matches the Python master and PHP, which both
-        # mirror warning+ rather than error+ -- error.log is "the stuff worth
-        # looking at", and a warning qualifies.
-        if @error_logger && level && (SEVERITY_MAP[level] || 0) >= SEVERITY_MAP[:warn]
-          @error_logger << "#{line}\n"
+
+        base = File.basename(path)
+        base.include?(".") && !base.start_with?(".")
+      end
+
+      def ensure_snapshot
+        discard_state_if_forked
+        configure if @snapshot.nil?
+        @snapshot
+      end
+
+      # Ruby has no built-in post-fork hook (Process.fork is a raw syscall
+      # wrapper), so a forked child inherits every class-level ivar's value
+      # at the instant of fork -- including an owned sink and any thread's
+      # request id snapshot at fork time (Decision 24 / LOG-Q05 requires a
+      # forked child to discard inherited state and resolve fresh).
+      # Detecting "my PID changed since I last touched this state" lazily,
+      # on every access, achieves the same observable effect as an eager
+      # fork hook.
+      def discard_state_if_forked
+        current = Process.pid
+        if !@pid.nil? && @pid != current
+          @snapshot = nil
+          Thread.current[:tina4_request_id] = nil
         end
-      rescue IOError, SystemCallError => e
-        raise if @strict
-        # Don't crash on log write failure
+        @pid = current
       end
     end
   end
+
+  # Tina4::Debug (backward-compat alias) is defined once in lib/tina4/debug.rb,
+  # not here, to avoid the "already initialized constant" redefinition warning.
 end