tina4ruby 3.13.97 → 3.13.99

data/lib/tina4/sql_translator.rb

@@ -17,84 +17,131 @@ module Tina4
   #
   class SQLTranslator
     class << self
-      # Convert LIMIT/OFFSET to Firebird ROWS...TO syntax.
+      # ── Literal-safe rewriting ────────────────────────────────────
       #
-      # LIMIT 10 OFFSET 5  =>  ROWS 6 TO 15
-      # LIMIT 10           =>  ROWS 1 TO 10
+      # A dialect rewrite (|| -> CONCAT, TRUE -> 1, ILIKE -> LOWER LIKE) must NEVER
+      # touch text inside a string literal, a quoted identifier or a comment: a
+      # column value of 'a||b', a label 'TRUE', or a LIKE pattern that mentions
+      # ILIKE is DATA, not SQL. Each transform masks every literal/identifier/
+      # comment to an opaque token, rewrites the masked SQL, then restores the
+      # tokens, so the rewrite only ever sees real SQL structure.
       #
-      # @param sql [String]
-      # @return [String]
-      def limit_to_rows(sql)
-        # Try LIMIT X OFFSET Y first
-        if (m = sql.match(/\bLIMIT\s+(\d+)\s+OFFSET\s+(\d+)\s*$/i))
-          limit = m[1].to_i
-          offset = m[2].to_i
-          start_row = offset + 1
-          end_row = offset + limit
-          return sql[0...m.begin(0)] + "ROWS #{start_row} TO #{end_row}"
-        end
+      # NOTE on the removed methods (SQLTRANS-DEC-02): +limit_to_rows+,
+      # +limit_to_top+ and +placeholder_style+ were deleted here. Ruby's DRIVERS
+      # own pagination and placeholders by design and do it correctly per engine
+      # (Firebird +SELECT FIRST/SKIP+, MSSQL +OFFSET ... FETCH+, Postgres +$1+),
+      # whereas these translator helpers emitted a DIFFERENT and inferior shape
+      # (MSSQL +TOP+, Firebird +ROWS x TO y+) that nothing called. Keeping a dead
+      # public method that also disagrees with the live driver is a footgun, so
+      # they are gone. concat/bool/ilike stay (they fill a real gap - the drivers
+      # do not translate them) and are now WIRED into the MySQL driver.
 
-        # Then try LIMIT X only
-        if (m = sql.match(/\bLIMIT\s+(\d+)\s*$/i))
-          limit = m[1].to_i
-          return sql[0...m.begin(0)] + "ROWS 1 TO #{limit}"
+      # Replace string literals, quoted identifiers and comments with opaque
+      # "\x00N\x00" tokens. Returns [masked_sql, literals]; doubled-quote escapes
+      # ('' "" ``) are handled so an embedded quote never ends the span early.
+      def mask_literals(sql)
+        literals = []
+        out = +""
+        i = 0
+        n = sql.length
+        while i < n
+          ch = sql[i]
+          nxt = sql[i + 1]
+          if ch == "'" || ch == '"' || ch == "`"
+            start = i
+            i += 1
+            while i < n
+              if sql[i] == ch
+                if sql[i + 1] == ch
+                  i += 2
+                  next
+                end
+                i += 1
+                break
+              end
+              i += 1
+            end
+            out << "\x00#{literals.length}\x00"
+            literals << sql[start...i]
+            next
+          end
+          if ch == "-" && nxt == "-"
+            start = i
+            i += 1 while i < n && sql[i] != "\n"
+            out << "\x00#{literals.length}\x00"
+            literals << sql[start...i]
+            next
+          end
+          if ch == "/" && nxt == "*"
+            start = i
+            i += 2
+            i += 1 while i < n && !(sql[i] == "*" && sql[i + 1] == "/")
+            i = [i + 2, n].min
+            out << "\x00#{literals.length}\x00"
+            literals << sql[start...i]
+            next
+          end
+          out << ch
+          i += 1
         end
-
-        sql
+        [out, literals]
       end
 
-      # Convert LIMIT to MSSQL TOP syntax.
-      #
-      # SELECT ... LIMIT 10  =>  SELECT TOP 10 ...
-      # OFFSET queries are left unchanged (not supported by TOP).
-      #
-      # @param sql [String]
-      # @return [String]
-      def limit_to_top(sql)
-        if (m = sql.match(/\bLIMIT\s+(\d+)\s*$/i)) && !sql.match?(/\bOFFSET\b/i)
-          limit = m[1].to_i
-          body = sql[0...m.begin(0)].strip
-          return body.sub(/^(SELECT)\b/i, "\\1 TOP #{limit}")
-        end
-
-        sql
+      # Inverse of #mask_literals.
+      def restore_literals(masked, literals)
+        masked.gsub(/\x00(\d+)\x00/) { literals[::Regexp.last_match(1).to_i] }
       end
 
-      # Convert || concatenation to CONCAT() for MySQL/MSSQL.
+      # Convert || string concatenation to CONCAT() for MySQL/MSSQL. Rewrites ONLY
+      # || operators joining expression operands OUTSIDE any string literal or
+      # comment, and only the operand chain - never the whole statement.
       #
-      # 'a' || 'b' || 'c'  =>  CONCAT('a', 'b', 'c')
+      #   SELECT a || b FROM t   =>  SELECT CONCAT(a, b) FROM t
+      #   WHERE data = 'a||b'    =>  WHERE data = 'a||b'   (literal untouched)
       #
       # @param sql [String]
       # @return [String]
       def concat_pipes_to_func(sql)
         return sql unless sql.include?("||")
 
-        parts = sql.split("||")
-        if parts.length > 1
-          "CONCAT(#{parts.map(&:strip).join(', ')})"
-        else
-          sql
+        masked, literals = mask_literals(sql)
+        return sql unless masked.include?("||")
+
+        chain = /#{SQLTranslator::PRIMARY}(?:\s*\|\|\s*#{SQLTranslator::PRIMARY})+/
+        rewritten = masked.gsub(chain) do |m|
+          "CONCAT(#{m.split(/\s*\|\|\s*/).join(', ')})"
         end
+        restore_literals(rewritten, literals)
       end
 
-      # Convert TRUE/FALSE to 1/0 for engines without boolean type.
+      # Convert a bare TRUE/FALSE to 1/0 for engines without a boolean type. A
+      # TRUE/FALSE INSIDE a string literal is data and is left untouched.
       #
       # @param sql [String]
       # @return [String]
       def boolean_to_int(sql)
-        sql.gsub(/\bTRUE\b/i, "1").gsub(/\bFALSE\b/i, "0")
+        return sql unless sql.match?(/\b(?:TRUE|FALSE)\b/i)
+
+        masked, literals = mask_literals(sql)
+        masked = masked.gsub(/\bTRUE\b/i, "1").gsub(/\bFALSE\b/i, "0")
+        restore_literals(masked, literals)
       end
 
-      # Convert ILIKE to LOWER() LIKE LOWER() for engines without ILIKE.
+      # Convert +col ILIKE pattern+ to +LOWER(col) LIKE LOWER(pattern)+ for engines
+      # without ILIKE. The pattern operand is captured whole (a multi-word
+      # '%two words%' survives), and an ILIKE INSIDE a string literal is untouched.
       #
       # @param sql [String]
       # @return [String]
       def ilike_to_like(sql)
-        sql.gsub(/(\S+)\s+ILIKE\s+(\S+)/i) do
-          col = ::Regexp.last_match(1).strip
-          val = ::Regexp.last_match(2).strip
-          "LOWER(#{col}) LIKE LOWER(#{val})"
+        return sql unless sql =~ /ilike/i
+
+        masked, literals = mask_literals(sql)
+        pattern = /(#{SQLTranslator::PRIMARY})\s+ILIKE\s+(#{SQLTranslator::PRIMARY})/i
+        rewritten = masked.gsub(pattern) do
+          "LOWER(#{::Regexp.last_match(1)}) LIKE LOWER(#{::Regexp.last_match(2)})"
         end
+        restore_literals(rewritten, literals)
       end
 
       # Translate AUTOINCREMENT across engines in DDL.
@@ -107,7 +154,13 @@ module Tina4
         when "mysql"
           sql.gsub("AUTOINCREMENT", "AUTO_INCREMENT")
         when "postgresql"
-          sql.gsub(/INTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT/i, "SERIAL PRIMARY KEY")
+          # BIGINT PRIMARY KEY AUTOINCREMENT -> BIGSERIAL (a real 64-bit sequence);
+          # INTEGER -> SERIAL. A plain BIGINT with the keyword merely stripped has
+          # no sequence and cannot auto-increment.
+          sql
+            .gsub(/\bBIGINT\s+PRIMARY\s+KEY\s+AUTOINCREMENT\b/i, "BIGSERIAL PRIMARY KEY")
+            .gsub(/\bINTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT\b/i, "SERIAL PRIMARY KEY")
+            .gsub(/\s*\bAUTOINCREMENT\b/i, "")
         when "mssql"
           sql.gsub(/AUTOINCREMENT/i, "IDENTITY(1,1)")
         when "firebird"
@@ -117,42 +170,13 @@ module Tina4
         end
       end
 
-      # Convert ? placeholders to engine-specific style.
-      #
-      # ?  =>  %s       (MySQL, PostgreSQL)
-      # ?  =>  :1, :2   (Oracle, Firebird)
-      #
-      # @param sql [String]
-      # @param style [String] target placeholder style: "%s" or ":"
-      # @return [String]
-      def placeholder_style(sql, style)
-        case style
-        when "%s"
-          sql.gsub("?", "%s")
-        when ":"
-          count = 0
-          sql.chars.map do |ch|
-            if ch == "?"
-              count += 1
-              ":#{count}"
-            else
-              ch
-            end
-          end.join
-        else
-          sql
-        end
-      end
-
-      # Generate a cache key for a query and its parameters.
-      #
-      # @param sql [String]
-      # @param params [Array, nil]
-      # @return [String]
-      def query_key(sql, params = nil)
-        raw = params ? "#{sql}|#{params.inspect}" : sql
-        "query:#{Digest::SHA256.hexdigest(raw)}"
-      end
+      # NOTE (SQLTRANS-DEC-02): +placeholder_style+ was removed - every Ruby
+      # driver owns its own placeholder shape (+?+ for MySQL/SQLite/MSSQL/Firebird,
+      # +$1+ for Postgres), so this helper had zero callers and disagreed with the
+      # live drivers. The cache KEY helper +query_key+ was also removed here: it
+      # duplicated the live +.query_key+ class method the ORM cache path (defined
+      # in lib/tina4/cache.rb, per spec/docs_truth_spec.rb's D12 lock-in that this
+      # file stays free of that class's name) actually uses. One source, not two.
 
       # Collapse a row-at-a-time INSERT batch into chunked multi-row VALUES.
       #
@@ -233,6 +257,11 @@ module Tina4
       end
     end
 
+    # A concat/ilike operand: a masked literal-or-identifier token, a simple
+    # function call, a (qualified) identifier, a placeholder, or a number. The
+    # function-call args exclude +|+ so a nested +||+ never splits the chain.
+    PRIMARY = '(?:\x00\d+\x00|[A-Za-z_][\w$]*\s*\([^()|]*\)|[A-Za-z_][\w$]*(?:\.[A-Za-z_][\w$]*)*|:[A-Za-z_]\w*|\$\d+|\?|%s|\d+(?:\.\d+)?)'
+
     # Hard per-statement bind-parameter ceiling per engine. 0 = never collapse.
     # Sourced from spec/fixtures/batch_write_contract.json, byte-identical in
     # all four frameworks.

data/lib/tina4/swagger.rb

@@ -173,10 +173,22 @@ module Tina4
         scheme && !scheme.empty? ? scheme : "bearerAuth"
       end
 
-      # Path filtering. Framework internals (/swagger, /__dev) are ALWAYS
+      # Framework-internal route prefixes that are NEVER part of an
+      # application's public API document. SHARED across all four frameworks
+      # (SWAG-EXCLUSION-NOT-SHARED, ADR-0004) so the exclusion is one rule
+      # everywhere, not three mechanisms: the dev tools (/swagger, /__dev),
+      # the feedback widget (/__feedback), and the built-in AI/RAG service
+      # probes (/ai, /rag, /vision, /embed, /image). Ruby dispatches these
+      # OUTSIDE Tina4::Router today, so most never reach included? in
+      # practice — the list is here so the RULE holds regardless of how a
+      # given route got registered, not because of where each internal
+      # happens to be wired.
+      INTERNAL_PREFIXES = ["/swagger", "/__dev", "/__feedback", "/ai", "/rag", "/vision", "/embed", "/image"].freeze
+
+      # Path filtering. Framework internals (INTERNAL_PREFIXES) are ALWAYS
       # excluded; then TINA4_SWAGGER_INCLUDE (allow-list) / _EXCLUDE apply.
       def included?(raw_path)
-        ["/swagger", "/__dev"].each do |internal|
+        INTERNAL_PREFIXES.each do |internal|
           return false if raw_path == internal || raw_path.start_with?("#{internal}/")
         end
 
@@ -240,11 +252,15 @@ module Tina4
         operation = {
           "operationId" => unique_operation_id(method, path, ctx[:seen_ids]),
           "summary" => meta[:summary] || "#{method.upcase} #{route.path}",
-          "description" => meta[:description] || "",
           "tags" => tags,
           "parameters" => build_parameters(route),
           "responses" => build_responses(meta, ref, ctx)
         }
+        # description is OMITTED when unset (SWAG-SHAPE-DRIFT, ADR-0004) —
+        # python/php/node never fabricate a description key either; Ruby used
+        # to always stamp "" on every undecorated operation, the one shape
+        # drift where Ruby (not Python) was the odd one out.
+        operation["description"] = meta[:description] if meta[:description]
 
         operation["deprecated"] = true if meta[:deprecated]
         operation["security"] = security unless security.nil?

data/lib/tina4/template.rb

@@ -5,6 +5,50 @@ module Tina4
     TEMPLATE_DIRS = %w[templates src/templates src/views views].freeze
 
     class << self
+      # Content negotiation for an error response (feature 42, ERR-DEC-02): does
+      # an Accept header prefer application/json over text/html?
+      #
+      # `Accept: application/json` (an API client) prefers JSON; a browser
+      # Accept (`text/html`, `*/*`, or no header at all) prefers HTML. A mixed
+      # Accept header - a real browser's
+      # `text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8` - is
+      # resolved by q-value: whichever of the two media types this method cares
+      # about is weighted higher wins; a tie or neither present defaults to
+      # HTML, the historical/back-compatible behaviour for an unspecified
+      # client. This is the ONE shared decision reused by the 403/404/500 error
+      # paths (#render_error's callers in rack_app.rb and middleware.rb), so a
+      # JSON API client sees the SAME negotiated shape everywhere
+      # (ERR-403-SPLIT) - ported with the same algorithm to Python/PHP/Node.
+      def wants_json?(accept)
+        accept = accept.to_s
+        return false if accept.empty?
+
+        best_json = -1.0
+        best_html = -1.0
+        accept.split(",").each do |part|
+          segments = part.strip.split(";")
+          media = segments[0].to_s.strip.downcase
+          q = 1.0
+          segments[1..].each do |param|
+            param = param.strip
+            next unless param.start_with?("q=")
+
+            q_str = param[2..]
+            q = q_str.to_f if q_str =~ /\A-?\d+(\.\d+)?\z/
+          end
+          if media == "application/json"
+            best_json = q if q > best_json
+          elsif ["text/html", "*/*", "application/xhtml+xml"].include?(media)
+            best_html = q if q > best_html
+          end
+        end
+
+        return false if best_json.negative?
+        return true if best_html.negative?
+
+        best_json > best_html
+      end
+
       def globals
         @globals ||= {}
       end
@@ -19,7 +63,7 @@ module Tina4
           raise "Template not found: #{template_path}"
         end
 
-        content = File.read(full_path)
+        content = File.read(full_path, encoding: "utf-8")
         ext = File.extname(full_path).downcase
         context = globals.merge(data.transform_keys(&:to_s))
 
@@ -43,7 +87,18 @@ module Tina4
           %w[.twig .html .erb].each do |ext|
             path = File.join(dir, "#{code}#{ext}")
             if File.exist?(path)
-              content = File.read(path)
+              # encoding: "utf-8" (feature 42, ERR-DEC-01): 403.twig ships an
+              # em-dash. Without a forced encoding, File.read tags the string
+              # with Encoding.default_external, which is UTF-8 on a typical
+              # dev machine but US-ASCII on a bare/minimal locale (no LANG/
+              # LC_ALL - common in a container) - and Ruby's regex engine then
+              # raises ArgumentError: invalid byte sequence in US-ASCII the
+              # moment TwigEngine tries to match against it. render_error's
+              # caller used to `rescue` broadly and silently fall back to a
+              # bare string, so every 403 request on such a host rendered NO
+              # template at all and nobody noticed. Matches lib/tina4/frond.rb,
+              # which already reads its templates this way.
+              content = File.read(path, encoding: "utf-8")
               return TwigEngine.new(context, dir).render(content)
             end
           end
@@ -123,7 +178,7 @@ module Tina4
 
       def error_overlay_source(file, line)
         return "" unless file && line && File.exist?(file)
-        lines = File.readlines(file)
+        lines = File.readlines(file, encoding: "utf-8")
         start = [line.to_i - 4, 0].max
         finish = [line.to_i + 3, lines.length - 1].min
         snippet = lines[start..finish].each_with_index.map do |l, i|
@@ -230,7 +285,7 @@ module Tina4
           parent_path = Regexp.last_match(1)
           full_parent = resolve_template(parent_path)
           if full_parent && File.exist?(full_parent)
-            parent_source = File.read(full_parent)
+            parent_source = File.read(full_parent, encoding: "utf-8")
             child_blocks = extract_blocks(content)
             @blocks.merge!(child_blocks)
             content = render_with_blocks(parent_source, @blocks)
@@ -296,7 +351,7 @@ module Tina4
           grandparent_name = Regexp.last_match(1)
           full_grandparent = resolve_template(grandparent_name)
           if full_grandparent && File.exist?(full_grandparent)
-            grandparent_source = File.read(full_grandparent)
+            grandparent_source = File.read(full_grandparent, encoding: "utf-8")
 
             # Extract block defaults defined in the parent template
             parent_blocks = extract_blocks(parent_source)
@@ -349,7 +404,7 @@ module Tina4
           inc_path = Regexp.last_match(1)
           full_path = resolve_template(inc_path)
           if full_path && File.exist?(full_path)
-            inc_content = File.read(full_path)
+            inc_content = File.read(full_path, encoding: "utf-8")
             TwigEngine.new(@context.dup, File.dirname(full_path)).render(inc_content)
           else
             "<!-- include not found: #{inc_path} -->"

data/lib/tina4/test_client.rb

@@ -22,12 +22,45 @@ module Tina4
     # Build from a Rack response tuple [status, headers, body_array]
     def initialize(rack_response)
       @status = rack_response[0]
-      @headers = rack_response[1] || {}
+      raw_headers = rack_response[1] || {}
+
+      # Rack folds a genuinely repeated header (Tina4::Response#to_rack only
+      # ever repeats Set-Cookie, joined "\n" — the Rack 2/3 convention for a
+      # multi-value header carried in a single hash slot) into ONE value; a
+      # header value can never legitimately contain a raw newline (RFC 7230),
+      # so splitting on "\n" is safe and general, not a Set-Cookie special
+      # case. @header_list keeps every occurrence, in emission order, so a
+      # duplicate is assertable via get_all(); @headers stays the back-compat
+      # single-value view — the LAST occurrence, the "last wins" contract the
+      # other three frameworks converge on — so nothing that reads a plain
+      # (never-repeated) header sees any change (TC-HEADER-COLLAPSE,
+      # TC-DEC-02).
+      @header_list = {}
+      flat = {}
+      raw_headers.each do |name, value|
+        key = name.to_s.downcase
+        values = value.is_a?(Array) ? value.map(&:to_s) : value.to_s.split("\n")
+        values = [""] if values.empty?
+        @header_list[key] = values
+        flat[key] = values.last
+      end
+      @headers = flat
+
       @content_type = @headers["content-type"] || ""
       raw_body = rack_response[2]
       @body = raw_body.is_a?(Array) ? raw_body.join : raw_body.to_s
     end
 
+    # Every value sent for +name+ (case-insensitive), in emission order.
+    #
+    # A header sent once returns a one-item array; a header never sent
+    # returns an empty array. This is the one place a duplicate response
+    # header (two Set-Cookie) is visible — headers[name] always collapses to
+    # the LAST value, same as before (TC-HEADER-COLLAPSE, TC-DEC-02).
+    def get_all(name)
+      (@header_list[name.to_s.downcase] || []).dup
+    end
+
     # Parse body as JSON.
     def json
       return nil if @body.nil? || @body.empty?
@@ -138,10 +171,23 @@ module Tina4
       env["CONTENT_TYPE"] = content_type unless content_type.empty?
       env["CONTENT_LENGTH"] = raw_body.bytesize.to_s unless raw_body.empty?
 
-      # Add custom headers (convert to Rack format: X-Custom → HTTP_X_CUSTOM)
+      # Add custom headers (convert to Rack format: X-Custom → HTTP_X_CUSTOM).
+      # Content-Type and Content-Length are the two CGI/Rack headers that do
+      # NOT get an HTTP_ prefix (Request#content_type reads env["CONTENT_TYPE"]
+      # directly) — without this a caller-supplied `headers: {"Content-Type"
+      # => ...}` silently landed in HTTP_CONTENT_TYPE, which nothing reads, so
+      # #content_type stayed "" and body parsing fell through to the generic
+      # {} branch regardless of what the caller asked for. PHP's/Node's/
+      # Python's TestClient never had this gap (their headers carry no CGI
+      # prefix convention to special-case).
       if headers
         headers.each do |key, value|
-          rack_key = "HTTP_#{key.upcase.tr('-', '_')}"
+          normalised = key.to_s.downcase
+          rack_key = case normalised
+                     when "content-type" then "CONTENT_TYPE"
+                     when "content-length" then "CONTENT_LENGTH"
+                     else "HTTP_#{key.upcase.tr('-', '_')}"
+                     end
           env[rack_key] = value
         end
       end

data/lib/tina4/testing.rb

@@ -41,32 +41,37 @@ module Tina4
       end
 
       # ── Inline testing (parity with Python/PHP/Node decorator pattern) ──
+      #
+      # The builders are named expect_* — DESCRIPTORS that record an expectation
+      # for run_all to execute later — deliberately distinct from the immediate
+      # xUnit-style TestContext#assert_* used inside describe/it blocks, so the two
+      # surfaces never collide on a name with an incompatible signature.
 
-      # Assertion builder: assert_equal(args, expected)
-      def assert_equal(args, expected)
+      # Expectation builder: expect_equal(args, expected)
+      def expect_equal(args, expected)
         { type: :equal, args: args, expected: expected }
       end
 
-      # Assertion builder: assert_raises(exception_class, args)
-      def assert_raises(exception_class, args)
+      # Expectation builder: expect_raises(exception_class, args)
+      def expect_raises(exception_class, args)
         { type: :raises, exception: exception_class, args: args }
       end
 
-      # Assertion builder: assert_true(args)
-      def assert_true(args)
+      # Expectation builder: expect_true(args)
+      def expect_true(args)
         { type: :true, args: args }
       end
 
-      # Assertion builder: assert_false(args)
-      def assert_false(args)
+      # Expectation builder: expect_false(args)
+      def expect_false(args)
         { type: :false, args: args }
       end
 
-      # Register a callable with inline assertions (mirrors Python's @tests decorator).
+      # Register a callable with inline expectations (mirrors Python's @tests decorator).
       #
       #   Tina4::Testing.tests(
-      #     Tina4::Testing.assert_equal([5, 3], 8),
-      #     Tina4::Testing.assert_raises(ArgumentError, [nil]),
+      #     Tina4::Testing.expect_equal([5, 3], 8),
+      #     Tina4::Testing.expect_raises(ArgumentError, [nil]),
       #   ) { |a, b| raise ArgumentError, "b required" if b.nil?; a + b }
       #
       def tests(*assertions, name: nil, &block)

data/lib/tina4/validator.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Tina4
   # Request body validator with chainable rules.
   #
@@ -140,7 +142,11 @@ module Tina4
       return self if value.nil?
 
       unless allowed.include?(value)
-        @validation_errors << { field: key, message: "#{key} must be one of #{allowed}" }
+        # Canonical wording (VALID-TWO-MESSAGES): render the allowed set as
+        # compact JSON so every framework prints the SAME list -- Node
+        # JSON.stringify, PHP json_encode, Python json.dumps and this to_json all
+        # emit ["admin","user","guest"] (no spaces), never a language repr.
+        @validation_errors << { field: key, message: "#{key} must be one of #{allowed.to_json}" }
       end
       self
     end

data/lib/tina4/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tina4
-  VERSION = "3.13.97"
+  VERSION = "3.13.99"
 end

data/lib/tina4/webserver.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "port_takeover"
+
 module Tina4
   class WebServer
     DEFAULT_HOST = "0.0.0.0"
@@ -17,49 +19,29 @@ module Tina4
       @port = port || Tina4.resolve_bind_port(DEFAULT_PORT)
     end
 
-    # Kill whatever process is listening on *port*.
-    # Uses lsof on macOS/Linux and netstat + taskkill on Windows.
-    # Raises RuntimeError if the port cannot be freed.
+    # Reclaim *port* from a stale Tina4 dev server via the shared, guarded path.
+    #
+    # This is the runtime bind-failure fallback. It used to SIGTERM whatever held
+    # the port with NONE of the CLI's guards -- no identity check, no container
+    # guard, no PID-safety filter -- so a foreign holder (another dev server, a
+    # database) was killed on any bind failure. It now routes through the SAME
+    # identity-checked helper the CLI uses (TAKEOVER-DEC-02), so only a
+    # PID-file-confirmed Tina4 dev server is ever signalled.
+    #
+    # Raises RuntimeError when the port is held by a non-Tina4 process (or
+    # takeover is opted out / disabled outside dev), so the bind fails loudly with
+    # a clear message instead of killing an innocent process.
     def free_port(port)
-      puts "  Port #{port} in use — killing existing process..."
-
-      if RUBY_PLATFORM =~ /mswin|mingw|cygwin/
-        output = `netstat -ano 2>&1`
-        pid = nil
-        output.each_line do |line|
-          if line.include?(":#{port}") && (line.include?("LISTENING") || line.include?("ESTABLISHED"))
-            parts = line.strip.split(/\s+/)
-            candidate = parts.last
-            if candidate =~ /^\d+$/
-              pid = candidate
-              break
-            end
-          end
-        end
-        if pid
-          system("taskkill /PID #{pid} /F")
-        else
-          raise "Could not free port #{port}: no PID found"
-        end
-      else
-        pids = `lsof -ti :#{port} 2>/dev/null`.strip.split("\n")
-        if pids.empty?
-          return # Nothing found — port may have freed itself
-        end
-        pids.each do |pid|
-          pid = pid.strip
-          next unless pid =~ /^\d+$/
-          begin
-            Process.kill("TERM", pid.to_i)
-          rescue Errno::ESRCH
-            # Process already gone
-          end
-        end
+      result = Tina4::PortTakeover.take_over_port(
+        port, dev: Tina4::PortTakeover.dev?, no_takeover: Tina4::PortTakeover.no_takeover_opted_out?
+      )
+      if result.reclaimed?
+        puts "  #{result.message}"
+        return
       end
+      raise result.message if result.refused?
 
-      # Give the OS a moment to reclaim the port
-      sleep(0.5)
-      puts "  Port #{port} freed"
+      # NOTHING / container: nothing to reclaim -- let the real bind decide.
     end
 
     def start
@@ -115,6 +97,10 @@ module Tina4
         AccessLog: []
       )
 
+      # Record THIS process as the Tina4 dev server on the main port, so a later
+      # `tina4 serve` can identify it as reclaimable (TAKEOVER-DEC-01).
+      Tina4::PortTakeover.write_pidfile(@port)
+
       # Setup graceful shutdown with WEBrick server reference
       Tina4::Shutdown.setup(server: @server)
 
@@ -327,6 +313,8 @@ module Tina4
       @ai_server&.shutdown
       @ai_thread&.join(5)
       @server&.shutdown
+      # Drop our identity marker so a later takeover does not match a dead PID.
+      Tina4::PortTakeover.remove_pidfile(@port)
     end
 
     # Dispatch a Rack-style env through the Tina4 app and return [status, headers, body].