tina4ruby 3.13.138 → 3.13.140

data/lib/tina4/graphql.rb

@@ -227,6 +227,14 @@ module Tina4
       @source = source
       @tokens = tokenize(source)
       @pos = 0
+      # F2: bound the parser's own recursion. A deeply nested query
+      # ("{a{a{a...}}}") otherwise recurses in parse_selection_set until Ruby
+      # raises SystemStackError — which is NOT a StandardError, so the public
+      # execute's `rescue => e` misses it and it escapes as a 500. Raising a
+      # GraphQLError (a StandardError) at the depth bound keeps it caught and
+      # returned as a clean GraphQL error. Reuses TINA4_GRAPHQL_MAX_DEPTH.
+      @depth = 0
+      @max_depth = Integer(ENV.fetch("TINA4_GRAPHQL_MAX_DEPTH", "50"), exception: false) || 50
     end
 
     def parse
@@ -439,6 +447,19 @@ module Tina4
     end
 
     def parse_selection_set
+      @depth += 1
+      if @max_depth.positive? && @depth > @max_depth
+        @depth -= 1
+        raise GraphQLError, "Query exceeds maximum depth of #{@max_depth}"
+      end
+      begin
+        parse_selection_set_inner
+      ensure
+        @depth -= 1
+      end
+    end
+
+    def parse_selection_set_inner
       expect(:punct, "{")
       selections = []
       until current&.value == "}"
@@ -599,14 +620,47 @@ module Tina4
   class GraphQLExecutor
     # max_depth bounds selection-set nesting (DoS / stack-overflow guard).
     # Threaded down from the owning GraphQL instance; <= 0 disables the guard.
-    attr_accessor :max_depth
+    attr_accessor :max_depth, :max_nodes
 
-    def initialize(schema, max_depth: 50)
+    def initialize(schema, max_depth: 50, max_nodes: 1000)
       @schema = schema
       @max_depth = max_depth
+      # F2: maximum expanded selection nodes per query. The depth guard bounds
+      # NESTING but not WIDTH — a fragment bomb stays shallow while expanding to
+      # millions of fields, and an alias explosion is not deep at all. This
+      # budget bounds the expanded selection tree (fragments expanded, each
+      # alias counted) so both are rejected before any resolver runs.
+      @max_nodes = max_nodes
+    end
+
+    # F2: count the expanded selection nodes, aborting past max_nodes. Fragment
+    # spreads are expanded (so a fragment bomb is counted, not the small
+    # unexpanded document) and every field — including each alias — counts once.
+    # Capped by max_nodes and by the depth cap, so a circular fragment trips the
+    # budget instead of looping and the check can never cost more than the budget.
+    def query_complexity(selections, fragments, depth, count)
+      depth_cap = (@max_depth && @max_depth.positive?) ? @max_depth : 1000
+      return count if depth > depth_cap
+
+      selections.each do |sel|
+        count += 1
+        return count if count > @max_nodes
+
+        case sel[:kind]
+        when :fragment_spread
+          frag = fragments[sel[:name]]
+          count = query_complexity(frag[:selection_set], fragments, depth + 1, count) if frag
+        when :inline_fragment
+          count = query_complexity(sel[:selection_set] || [], fragments, depth + 1, count)
+        else
+          count = query_complexity(sel[:selection_set], fragments, depth + 1, count) if sel[:selection_set]
+        end
+        return count if count > @max_nodes
+      end
+      count
     end
 
-    def execute(document, variables: {}, context: {}, operation_name: nil)
+    def execute(document, variables: {}, context: {}, operation_name: nil, allow_mutations: true)
       # Collect fragments
       fragments = {}
       operations = []
@@ -631,9 +685,28 @@ module Tina4
 
       raise GraphQLError, "Unknown operation: #{operation_name}" unless operation
 
+      # F2: reject an over-complex query (fragment bomb / alias explosion) before
+      # any resolver runs.
+      if @max_nodes && @max_nodes.positive?
+        complexity = query_complexity(operation[:selection_set], fragments, 1, 0)
+        if complexity > @max_nodes
+          return { "data" => nil,
+                   "errors" => [{ "message" => "Query exceeds maximum complexity of #{@max_nodes} nodes" }] }
+        end
+      end
+
       # Resolve variables
       resolved_vars = resolve_variables(operation[:variables], variables)
 
+      # F4 (CSRF): a mutation must never run over a GET. A cross-site GET (an
+      # <img>/<script> src, a pre-rendered link) carries the victim's cookies
+      # and would otherwise trigger a state change. The GET handler passes
+      # allow_mutations: false; POST (which a browser cannot cross-site forge
+      # with a JSON content-type without a CORS preflight) still allows them.
+      if operation[:operation] == :mutation && !allow_mutations
+        raise GraphQLError, "Mutations are not allowed over GET"
+      end
+
       # Choose root fields
       root_fields = case operation[:operation]
                     when :query    then @schema.queries
@@ -897,6 +970,15 @@ module Tina4
       @executor&.max_depth = value
     end
 
+    # F2 complexity budget — see GraphQLExecutor#max_nodes. Writer keeps the
+    # executor in sync so tests/app code can override it.
+    attr_reader :max_nodes
+
+    def max_nodes=(value)
+      @max_nodes = value
+      @executor&.max_nodes = value
+    end
+
     # Class-level toggle for ORM auto-schema generation. Defaults to true,
     # can be disabled via TINA4_GRAPHQL_AUTO_SCHEMA=false. Initializers and
     # user app code can branch on this before calling `schema.from_orm(...)`.
@@ -969,7 +1051,10 @@ module Tina4
       # GraphQL DoS / stack-overflow vector. Default 50 is far beyond any
       # legitimate query; TINA4_GRAPHQL_MAX_DEPTH <= 0 disables the guard.
       @max_depth = Integer(ENV.fetch("TINA4_GRAPHQL_MAX_DEPTH", "50"), exception: false) || 50
-      @executor = GraphQLExecutor.new(@schema, max_depth: @max_depth)
+      # F2: expanded-node (complexity) budget — bounds query WIDTH (fragment
+      # bombs, alias explosions), which the depth guard does not.
+      @max_nodes = Integer(ENV.fetch("TINA4_GRAPHQL_MAX_NODES", "1000"), exception: false) || 1000
+      @executor = GraphQLExecutor.new(@schema, max_depth: @max_depth, max_nodes: @max_nodes)
       @field_resolvers = {}
 
       # Drain any resolvers registered via the class-level GraphQL.resolve()
@@ -1010,10 +1095,11 @@ module Tina4
     end
 
     # Execute a query string directly
-    def execute(query, variables: {}, context: {}, operation_name: nil)
+    def execute(query, variables: {}, context: {}, operation_name: nil, allow_mutations: true)
       parser = GraphQLParser.new(query)
       document = parser.parse
-      @executor.execute(document, variables: variables, context: context, operation_name: operation_name)
+      @executor.execute(document, variables: variables, context: context,
+                        operation_name: operation_name, allow_mutations: allow_mutations)
     rescue GraphQLError => e
       { "data" => nil, "errors" => [{ "message" => e.message }] }
     rescue => e
@@ -1083,6 +1169,16 @@ module Tina4
 
       graphql = self
       Tina4.post path, auth: false do |request, response|
+        # F4 (CSRF): require an application/json content-type. A browser can
+        # only send a cross-site POST with text/plain, form-urlencoded or
+        # multipart bodies without a CORS preflight; demanding JSON forces the
+        # preflight (and its same-origin/allow-list check) for any cross-site
+        # caller, so a forged form cannot drive a mutation. Same-origin XHR/
+        # fetch and server clients set application/json and are unaffected.
+        unless request.content_type.to_s.downcase.include?("application/json")
+          next response.json({ "data" => nil, "errors" => [{ "message" =>
+            "GraphQL requires a Content-Type of application/json" }] }, 415)
+        end
         # handle_request expects the raw JSON text (it JSON.parses internally),
         # so read body_raw — request.body now returns the PARSED payload.
         body = request.body_raw
@@ -1090,13 +1186,15 @@ module Tina4
         response.json(result)
       end
 
-      # Optional: GET for GraphiQL/introspection
+      # Optional: GET for GraphiQL/introspection. Queries only — a mutation over
+      # GET is refused (F4), since a cross-site GET carries the victim's cookies.
       Tina4.get path, auth: false do |request, response|
         query = request.query["query"]
         if query
           variables = request.query["variables"]
           variables = Tina4.parse_json(variables) if variables.is_a?(String) && !variables.empty?
-          result = graphql.execute(query, variables: variables || {}, context: { request: request })
+          result = graphql.execute(query, variables: variables || {},
+                                   context: { request: request }, allow_mutations: false)
           response.json(result)
         else
           response.html(graphiql_html(path))

data/lib/tina4/job.rb

@@ -113,9 +113,22 @@ module Tina4
       self
     end
 
-    # Reject this job with a reason. Alias for fail().
+    # Reject this job permanently — dead-letter it NOW, no retry (ADR-0023).
+    #
+    # Distinct from fail(): fail() records a failed attempt and only
+    # dead-letters once max_retries is exhausted (the job is retried first).
+    # reject() is for a message the consumer KNOWS is poison — it goes straight
+    # to the dead-letter store on this call. AMQP basic.reject(requeue=false)
+    # semantics. Was a literal alias for fail() before 3.13.139.
     def reject(reason = "")
-      fail(reason)
+      unless @queue
+        @attempts += 1
+        @status = :dead
+        return self
+      end
+      @queue.backend.reject(self, reason)
+      @status = :dead
+      self
     end
   end
 end

data/lib/tina4/mcp.rb

@@ -159,7 +159,9 @@ module Tina4
   #
   # Python master parity: tina4_python.mcp.is_loopback.
   def self.is_loopback?(ip)
-    return true if ip.nil? || ip.to_s.empty?
+    # An empty or missing peer is UNKNOWN and is not loopback: a runtime path
+    # that lost its socket address must fail closed (ADR-0079 s4).
+    return false if ip.nil? || ip.to_s.empty?
 
     addr = ip.to_s.strip.downcase
     addr = addr[7..] if addr.start_with?("::ffff:")

data/lib/tina4/middleware.rb

@@ -677,7 +677,9 @@ module Tina4
         auth_header = (headers["authorization"] || headers["Authorization"] || "").to_s
         if auth_header.start_with?("Bearer ")
           bearer_token = auth_header[7..].to_s.strip
-          return [request, response] if !bearer_token.empty? && Tina4::Auth.valid_token(bearer_token)
+          # Only an IDENTITY token marks an API client; a form token in the
+          # Bearer slot is not one and does not skip the check (ADR-0079 s1).
+          return [request, response] if !bearer_token.empty? && Tina4::Auth.identity_payload?(Tina4::Auth.valid_token(bearer_token))
         end
 
         # 7. A token in the query string leaks through logs/referers/history --

data/lib/tina4/push.rb

@@ -11,6 +11,7 @@ require_relative "base64"
 require "json"
 require "net/http"
 require "uri"
+require_relative "ssrf"
 
 module Tina4
   class PushError < StandardError; end
@@ -40,7 +41,11 @@ module Tina4
       bytes.b.rjust(32, "\x00".b)
     end
 
-    def initialize(subject: nil, public_key: nil, private_key: nil, ttl: 60, urgency: nil)
+    def initialize(subject: nil, public_key: nil, private_key: nil, ttl: 60, urgency: nil, allow_hosts: nil)
+      # SSRF guard (ADR-0084): the push endpoint is refused when it resolves to a
+      # private/internal address unless TINA4_ALLOW_PRIVATE_REQUESTS is truthy or
+      # the host/CIDR is on this allow-list.
+      @allow_hosts = allow_hosts || []
       @subject = (subject || ENV.fetch("TINA4_VAPID_SUBJECT", "")).strip
       @public_key = (public_key || ENV.fetch("TINA4_VAPID_PUBLIC", "")).strip
       @private_key = (private_key || ENV.fetch("TINA4_VAPID_PRIVATE", "")).strip
@@ -88,6 +93,13 @@ module Tina4
     end
 
     def deliver(endpoint, uri, subject, public_key, private, public, body)
+      # SSRF guard (ADR-0084): refuse a private/internal push endpoint. Net::HTTP
+      # does not follow redirects, so guarding the endpoint is sufficient.
+      begin
+        Tina4::Ssrf.guard_url!(uri, @allow_hosts)
+      rescue Tina4::SsrfError => e
+        raise PushError, e.message
+      end
       request = Net::HTTP::Post.new(uri)
       request["Authorization"] = "vapid t=#{vapid_token(uri, subject, private, public)}, k=#{public_key}"
       request["Content-Encoding"] = "aes128gcm"

data/lib/tina4/queue_backends/kafka_backend.rb

@@ -267,6 +267,14 @@ module Tina4
         out
       end
 
+      # Reject a job permanently — dead-letter it NOW, no retry (ADR-0023).
+      def reject(job, reason = "")
+        job.attempts = [job.attempts + 1, @max_retries].max
+        job.error = reason
+        dead_letter(job)
+        acknowledge(job)
+      end
+
       def failed(_topic, max_retries: 3)
         raise NotImplementedError,
               "The kafka queue backend cannot answer failed(): a job that failed " \

data/lib/tina4/queue_backends/lite_backend.rb

@@ -177,6 +177,18 @@ module Tina4
       # Aligns with retry_job(id) which had always unlinked the dead-letter
       # file — two spellings of the same intent that previously diverged.
       # Increments attempts, clears the error.
+      # Reject a job permanently — dead-letter it NOW, no retry (ADR-0023).
+      # Unlike fail(), which requeues until max_retries is spent, reject() moves
+      # a known-poison job straight to the dead-letter store. attempts is floored
+      # at max_retries so dead_letters (attempts >= limit) returns it and
+      # dead_letter_count agrees.
+      def reject(job, reason = "")
+        clear_reservation(job.topic, job.id)
+        job.attempts = [job.attempts + 1, @max_retries].max
+        job.error = reason
+        move_to_dead_letter(job, reason)
+      end
+
       def retry(job, delay_seconds: 0)
         clear_reservation(job.topic, job.id)
         # Drop any dead-letter file for this id BEFORE the re-queue: if this

data/lib/tina4/queue_backends/mongo_backend.rb

@@ -284,6 +284,18 @@ module Tina4
       # the normal path. This method did not exist at all, and Queue#failed
       # silently returned [] for it — indistinguishable from "nothing has
       # failed" (ADR-0022 decision 7).
+      # Reject a job permanently — dead-letter it NOW, no retry (ADR-0023).
+      def reject(job, reason = "")
+        job.attempts = [job.attempts + 1, @max_retries].max
+        job.error = reason
+        collection.find_one_and_update(
+          { _id: job.id },
+          { "$set" => { status: "dead", topic: "#{job.topic}.dead_letter",
+                        attempts: job.attempts, error: reason, reserved_at: nil } },
+          upsert: true
+        )
+      end
+
       def failed(topic, max_retries: 3)
         collection.find(
           topic: topic,

data/lib/tina4/queue_backends/rabbitmq_backend.rb

@@ -177,6 +177,14 @@ module Tina4
         end
       end
 
+      # Reject a job permanently — dead-letter it NOW, no retry (ADR-0023).
+      def reject(job, reason = "")
+        job.attempts = [job.attempts + 1, @max_retries].max
+        job.error = reason
+        dead_letter(job)
+        complete(job)
+      end
+
       def failed(_topic, max_retries: 3)
         raise NotImplementedError,
               "The rabbitmq queue backend cannot answer failed(): a job that " \

data/lib/tina4/rack_app.rb

@@ -1189,68 +1189,46 @@ module Tina4
     def self.enforce_route_auth(env, route)
       return nil unless route.auth_required
 
-      token = nil
-      token_source = nil  # :header, :body, :session
-
-      # Priority 1: Authorization Bearer header
+      unauthorized = [401, { "content-type" => "application/json" }, [JSON.generate({ error: "Unauthorized" })]]
+
+      # Token slots in priority order: Authorization Bearer header, then the
+      # body formToken (frond.js puts the auth token it received as a
+      # FreshToken there), then the session. The first slot holding a token
+      # decides, EXCEPT that a form token ("type" => "form") proves where a
+      # write came from, not who sent it: it is skipped and the next slot is
+      # tried (ADR-0079 s1). So a logged-in user posting a rendered form (form
+      # token in the body, auth token in the session) is still authenticated.
+      candidates = []
       auth_header = env["HTTP_AUTHORIZATION"] || ""
-      if auth_header =~ /\ABearer\s+(.+)\z/i
-        token = Regexp.last_match(1)
-        token_source = :header
-      end
+      candidates << [Regexp.last_match(1), :header] if auth_header =~ /\ABearer\s+(.+)\z/i
+      form_token = _extract_form_token(_read_rack_body(env), env)
+      candidates << [form_token, :body] if form_token && !form_token.empty?
 
-      # Priority 2: formToken from request body (for frond.js saveForm with {{ form_token() }})
-      if token.nil?
-        body_str = _read_rack_body(env)
-        form_token = _extract_form_token(body_str, env)
-        if form_token && !form_token.empty?
-          token = form_token
-          token_source = :body
-        end
+      verdict = candidates.each do |token, source|
+        outcome = _authenticate_token(env, token, source)
+        break outcome unless outcome == :skip
       end
+      return unauthorized if verdict == :denied
 
-      # Priority 3: Session token (for secured GET routes after login)
-      if token.nil?
+      unless env.key?("tina4.auth_payload")
         # Request path, so the same log-loud-then-degrade policy as
         # Request#session (ADR-0021): an unreachable session store must not turn
         # the auth gate into a 500. It degrades to an empty session, which means
         # no token, which means the ordinary 401 below - a SERVED request.
         session = Tina4::Session.new(env, degrade_on_backend_failure: true)
-        sso = session.get("_tina4_sso")
-        identity = sso.is_a?(Hash) ? sso["identity"] : nil
-        if identity.is_a?(Hash) && identity["issuer"] && identity["subject"]
+        # A provider-verified OIDC identity counts only while it is live
+        # (ADR-0079 s5).
+        identity = Tina4::Sso.live_session_identity(session.get("_tina4_sso"))
+        if identity
           env["tina4.auth_payload"] = identity
-          deny = rbac_forbidden(route, identity)
-          return deny if deny
-
-          return nil
-        end
-        session_token = session.get("token")
-        if session_token && !session_token.empty?
-          token = session_token
-          token_source = :session
-        end
-      end
-
-      # API_KEY bypass — routed through the timing-safe Tina4::Auth.validate_api_key
-      # (OpenSSL.fixed_length_secure_compare), matching tina4_python's _check_auth.
-      # It used to be a plain `token == api_key`, which returns as soon as two
-      # bytes differ — so response timing leaks the key prefix and the key can be
-      # recovered a character at a time. validate_api_key also covers the unset /
-      # blank / wrong-length cases the old guard spelled out by hand.
-      if Tina4::Auth.validate_api_key(token)
-        env["tina4.auth_payload"] = { "_auth" => "api_key" }
-      elsif token
-        unless Tina4::Auth.valid_token(token)
-          return [401, { "content-type" => "application/json" }, [JSON.generate({ error: "Unauthorized" })]]
+        else
+          session_token = session.get("token")
+          if session_token.is_a?(String) && !session_token.empty?
+            return unauthorized unless _authenticate_token(env, session_token, :session) == :accepted
+          end
         end
-        env["tina4.auth_payload"] = Tina4::Auth.get_payload(token)
-
-        # When body formToken validates, store a refreshed token for the FreshToken response header
-        env["tina4.fresh_token"] = Tina4::Auth.refresh_token(token) if token_source == :body
-      else
-        return [401, { "content-type" => "application/json" }, [JSON.generate({ error: "Unauthorized" })]]
       end
+      return unauthorized unless env.key?("tina4.auth_payload")
 
       # ── RBAC guards (Feature 138): authorization AFTER authentication ──
       # Auth has passed (401 ruled out above). If the route carries role/
@@ -1261,6 +1239,30 @@ module Tina4
       nil
     end
 
+    # Judge one token from one slot: :accepted (env["tina4.auth_payload"] set),
+    # :skip (a valid form token - not an identity, try the next slot) or
+    # :denied (anything else).
+    #
+    # API_KEY bypass - routed through the timing-safe Tina4::Auth.validate_api_key
+    # (OpenSSL.fixed_length_secure_compare), matching tina4_python's _check_auth.
+    # A plain `token == api_key` returns as soon as two bytes differ, so response
+    # timing would leak the key a character at a time.
+    def self._authenticate_token(env, token, source)
+      if Tina4::Auth.validate_api_key(token)
+        env["tina4.auth_payload"] = { "_auth" => "api_key" }
+        return :accepted
+      end
+      payload = Tina4::Auth.valid_token(token)
+      return :denied unless payload
+      return :skip unless Tina4::Auth.identity_payload?(payload)
+
+      env["tina4.auth_payload"] = payload
+      # When a body token authenticates, store a refreshed token for the
+      # FreshToken response header (identity tokens only).
+      env["tina4.fresh_token"] = Tina4::Auth.refresh_token(token) if source == :body
+      :accepted
+    end
+
     # Build a 403 Rack tuple when a route's RBAC guards are not satisfied by the
     # verified payload, else nil. AND across guard groups, OR within a group.
     # Roles read the `roles` claim (legacy singular `role` coerced); permissions

data/lib/tina4/realtime/s3_storage.rb

@@ -15,7 +15,15 @@ module Tina4
     class S3Storage < StorageBackend
       def initialize(endpoint: nil, key: nil, secret: nil, bucket: nil, region: nil)
         super()
-        require "aws-sdk-s3" # optional dependency, loaded lazily
+        begin
+          require "aws-sdk-s3" # optional dependency, loaded lazily
+        rescue LoadError
+          # Storage.select rescues this and falls back to local; its warning
+          # carries this message, so the remedy reaches the operator.
+          raise LoadError,
+                "The 'aws-sdk-s3' gem is required for S3Storage. Install it with: " \
+                "bundle add aws-sdk-s3 (or add gem \"aws-sdk-s3\" to your Gemfile)"
+        end
 
         @bucket = bucket || ENV["TINA4_STORAGE_BUCKET"]
         raise ArgumentError, "S3Storage requires TINA4_STORAGE_BUCKET" if @bucket.nil? || @bucket.empty?

data/lib/tina4/request.rb

@@ -292,6 +292,11 @@ module Tina4
     # still see the URL the client used. Matches Python/PHP/Node parity.
     def url
       scheme = self.class.secure_scheme?(env) ? "https" : "http"
+      # X-Forwarded-Host is honoured ONLY when the raw socket peer is a trusted
+      # proxy (TINA4_TRUSTED_PROXIES) — the same gate already applied to
+      # X-Forwarded-For. An untrusted client can otherwise forge the host and
+      # control the absolute request.url (password-reset links, cache keys,
+      # open-redirect base). Parity with Python/PHP/Node.
       forwarded_host = Tina4.trusted_proxy?(@remote_ip) ? env["HTTP_X_FORWARDED_HOST"] : nil
       host = forwarded_host || env["HTTP_HOST"] || env["SERVER_NAME"] || "localhost"
       port = env["SERVER_PORT"]

data/lib/tina4/row_symbolizer.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+module Tina4
+  # Shared row/key symbolisation for the two SQLite classes.
+  #
+  # `symbolize_rows`/`symbolize_keys` used to be byte-identical copy-paste in
+  # Tina4::Drivers::SqliteDriver and Tina4::Adapters::Sqlite3Adapter (the
+  # adapter's own comment pointed at the driver's copy). This module is the
+  # single home for the logic; both classes `include` it as private instance
+  # methods, so both share ONE implementation and can never drift again.
+  #
+  # The mapping is computed ONCE per query rather than per cell: the per-row
+  # form ran `k.to_s.to_sym` and an `is_a?` guard PER CELL, so a 5,000-row x
+  # 6-column fetch did 30,000 conversions for 6 distinct keys and made Tina4 the
+  # slowest of the four frameworks at bulk reads (Select ALL 5,000 rows:
+  # 10.16ms vs raw sqlite3 2.56ms). Hoisting the mapping out of the loop roughly
+  # halves the hydration cost with byte-identical output.
+  #
+  # The is_a?(String|Symbol) guard is preserved: older sqlite3 gems put
+  # positional Integer keys in the hash alongside the string names, and those
+  # must still be dropped.
+  module RowSymbolizer
+    private
+
+    # Symbolize a whole result set's keys, computing the mapping once per query.
+    def symbolize_rows(rows)
+      return rows if rows.empty?
+
+      str_keys = rows.first.keys.select { |k| k.is_a?(String) || k.is_a?(Symbol) }
+      sym_keys = str_keys.map(&:to_sym)
+      count = str_keys.length
+      rows.map do |row|
+        out = {}
+        i = 0
+        while i < count
+          out[sym_keys[i]] = row[str_keys[i]]
+          i += 1
+        end
+        out
+      end
+    end
+
+    # Single-hash convenience; delegates to the batch path so there is one
+    # implementation of the mapping rule.
+    def symbolize_keys(hash)
+      symbolize_rows([hash]).first
+    end
+  end
+end

data/lib/tina4/session_handlers/database_handler.rb

@@ -217,25 +217,49 @@ module Tina4
       # spells "already exists" differently ("There is already an object named",
       # "already exists", SQLSTATE 42S01) and a string match would rot the first
       # time an engine reworded itself or ran under another locale.
+      #
+      # The re-check is RETRIED, a bounded number of times, because the loser
+      # can fail BEFORE the winner has committed. MEASURED on MySQL 8.4: CREATE
+      # TABLE IF NOT EXISTS takes a shared metadata lock on the name, checks,
+      # then upgrades it to exclusive, and two sessions upgrading at once is a
+      # metadata-lock deadlock. MySQL backs the victim off silently only when the
+      # session holds no other metadata lock; otherwise the victim gets 1213
+      # "Deadlock found" while the winner's table is still invisible, and one
+      # immediate re-check turned that lost race into a failed request (tina4-php
+      # CI run 35972320442). Same attempts and delays in all four frameworks.
+      CREATE_ATTEMPTS = 5
+      CREATE_RETRY_DELAY = 0.05
+
       def ensure_table
         return if @table_ready
 
         @table_ready = true
-        begin
-          db.execute(create_table_sql)
-        rescue StandardError
-          # A failed statement leaves PostgreSQL's transaction ABORTED, so
-          # without this the re-check would fail for the wrong reason and report
-          # a missing table that is right there. Best effort: an engine with no
-          # open transaction is entitled to object to being rolled back.
+        attempt = 1
+        until db.table_exists?(TABLE_NAME)
           begin
-            db.rollback
+            db.execute(create_table_sql)
+            return
           rescue StandardError
-            nil
+            # A failed statement leaves PostgreSQL's transaction ABORTED, so
+            # without this the re-check would fail for the wrong reason and
+            # report a missing table that is right there. Best effort: an engine
+            # with no open transaction is entitled to object to being rolled back.
+            begin
+              db.rollback
+            rescue StandardError
+              nil
+            end
+            # Somebody else created it - that is the race, and it is a success.
+            # Still absent after the last attempt is a real failure, re-raised
+            # untouched.
+            if attempt >= CREATE_ATTEMPTS
+              return if db.table_exists?(TABLE_NAME)
+
+              raise
+            end
+            sleep(CREATE_RETRY_DELAY * attempt)
+            attempt += 1
           end
-          # Somebody else created it - that is the race, and it is a success.
-          # Anything else is a real failure and is re-raised untouched.
-          raise unless db.table_exists?(TABLE_NAME)
         end
       end
     end