tina4ruby 3.13.137 → 3.13.138

data/lib/tina4/dispatch_pipeline.rb

@@ -1,4 +1,10 @@
 # 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/.
+
 
 require "zlib"
 require "stringio"
@@ -77,13 +83,24 @@ module Tina4
     # Content-Length reflects the (possibly compressed) body the equivalent
     # GET would have sent, mirroring the Python master's build_headers() ->
     # app() ordering (compress -> tag -> 304-decide -> strip-for-HEAD).
+    #
+    # `security_headers` is here for the same reason: a refusal (a CSRF 403, a
+    # legacy auth_handler 403, a pre-match middleware's 429), a 404 and a
+    # static file are all produced OUTSIDE the post-match middleware pass that
+    # runs SecurityHeadersMiddleware, so they left without CSP, nosniff and
+    # X-Frame-Options (python #137, php CSRF-403 parity).
     ALWAYS_STAGES = %i[
       compress_and_tag
       conditional_get
       head_strip
       apply_cors
+      security_headers
     ].freeze
 
+    # The three headers whose presence shows SecurityHeadersMiddleware already
+    # ran for this response (lower-case: how the pipeline stores them).
+    SECURITY_HEADER_PROBE = %w[content-security-policy x-content-type-options x-frame-options].freeze
+
     RESPONSE_STAGES = %i[
       dev_inspector_capture
       request_log
@@ -130,7 +147,7 @@ module Tina4
     DispatchContext = Struct.new(
       :env, :method, :path, :started_at,
       :pre_request, :pre_response, :matched_pattern, :matched,
-      :bypass_response_stages,
+      :bypass_response_stages, :security_exempt,
       keyword_init: true
     )
 
@@ -172,11 +189,22 @@ module Tina4
     # WebSocket upgrade - match against registered ws_routes.
     def websocket_upgrade(ctx)
       return nil unless websocket_upgrade?(ctx.env)
+      # The AI/test port never holds a live-reload socket: fall through to
+      # dev_routes, which answers "Not available on AI port" (Python's built-in
+      # server refuses the same upgrade with 404).
+      return nil if ctx.path == "/__dev_reload" && ctx.env["tina4.ai_port"]
+
+      # ADR-0082: the dev reload socket answers only a loopback / TINA4_HOST
+      # Host - the same rule the /__dev HTTP gate applies (DNS rebinding).
+      if ctx.path.start_with?("/__dev") && !Tina4::DevAdmin.dev_host_allowed?(ctx.env)
+        return [403, { "content-type" => "text/plain" }, ["Forbidden: host not allowed"]]
+      end
 
       ws_result = Tina4::Router.find_ws_route(ctx.path)
       return nil unless ws_result
 
       ws_route, ws_params = ws_result
+      ctx.security_exempt = true # a protocol switch, not a document
       handle_websocket_upgrade(ctx.env, ws_route, ws_params)
     end
 
@@ -190,6 +218,9 @@ module Tina4
         return [404, { "content-type" => "text/plain" }, ["Not available on AI port"]]
       end
 
+      # The dev dashboard is a debug-only surface with its own inline scripts;
+      # it keeps its historical headers.
+      ctx.security_exempt = true
       Tina4::DevAdmin.handle_request(ctx.env)
     end
 
@@ -284,11 +315,15 @@ module Tina4
     # 9110 s9.3.2. Recorded as a finding and fixed separately with its own test
     # pair - NOT silently inside this extraction.
     def not_found(ctx)
+      # The swagger UI loads its assets from TINA4_SWAGGER_UI_CDN, which the
+      # default CSP (default-src 'self') would block, so it stays exempt.
       if ctx.path == "/swagger" || ctx.path == "/swagger/"
         ctx.bypass_response_stages = true
+        ctx.security_exempt = true
         return serve_swagger_ui
       elsif ctx.path == "/swagger/openapi.json"
         ctx.bypass_response_stages = true
+        ctx.security_exempt = true
         return serve_openapi_json
       end
 
@@ -301,6 +336,56 @@ module Tina4
       handle_404(ctx.path, ctx.env["HTTP_ACCEPT"])
     end
 
+    # ALWAYS stage: every response gets the security headers a route response
+    # gets, whichever stage produced it. See ALWAYS_STAGES.
+    def security_headers(ctx, response)
+      return nil if ctx.security_exempt
+
+      with_security_headers(ctx, response)
+    end
+
+    # Issue #137 (parity with tina4-python #137): a static file gets the SAME
+    # security headers a route response gets.
+    #
+    # SecurityHeadersMiddleware is post-match global middleware, so it only ever
+    # ran for a MATCHED route; a file from public/ or src/public/ answers from
+    # this not-found fallback and skipped it. The same HTML carried CSP, nosniff
+    # and X-Frame-Options from a route and none of them as a file - and since
+    # "/" resolves to index.html, an SPA's front door was frameable
+    # (clickjacking) and ran without a CSP.
+    #
+    # Only this middleware is applied, and only when it is ATTACHED (which
+    # Tina4.initialize! does by default), so removing it still opts a static
+    # file out too. The headers come from the middleware's own before hook, so
+    # the TINA4_CSP / TINA4_FRAME_OPTIONS / TINA4_HSTS rules stay in one place.
+    # Other global middleware (auth, CSRF, rate limits) is deliberately NOT run
+    # here: static serving has never been subject to it. A header the file
+    # response already set is never overwritten.
+    def with_security_headers(ctx, triple)
+      return nil unless Tina4::Middleware.global_middleware.include?(Tina4::SecurityHeadersMiddleware)
+
+      status, headers, body = triple
+      # Header names are compared case-insensitively: a route response carries
+      # them as the middleware spelled them ("X-Frame-Options").
+      present = headers.keys.map { |name| name.to_s.downcase }
+      # A matched route already ran the middleware's hook.
+      return nil if SECURITY_HEADER_PROBE.all? { |name| present.include?(name) }
+
+      probe = Tina4::Response.new
+      defaults = probe.headers.keys
+      request = ctx.pre_request || Tina4::Request.new(ctx.env)
+      Tina4::SecurityHeadersMiddleware.before_security(request, probe)
+
+      merged = headers.dup
+      probe.headers.each do |name, value|
+        next if defaults.include?(name)
+
+        key = name.to_s.downcase
+        merged[key] = value unless present.include?(key)
+      end
+      [status, merged, body]
+    end
+
     # ── ALWAYS STAGES (compression / ETag / conditional-GET) ──────────
     # Each returns a replacement Rack triple, or nil to leave it unchanged.
 

data/lib/tina4/docs.rb

@@ -1,4 +1,10 @@
 # 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/.
+
 
 # Tina4::Docs — Live API RAG.
 #

data/lib/tina4/docstore.rb

@@ -1,4 +1,10 @@
 # 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/.
+
 
 # Tina4 DocStore - pymongo-style document storage with a zero-config SQLite fallback.
 #
@@ -47,6 +53,7 @@ require "json"
 require "time"
 require "securerandom"
 require "delegate"
+require_relative "sqlite3_gem"
 
 module Tina4
   module DocStore
@@ -190,12 +197,24 @@ module Tina4
 
     COMPARATORS = { "$gt" => ">", "$gte" => ">=", "$lt" => "<", "$lte" => "<=" }.freeze
 
+    FIELD_SEGMENT_RE = /\A[A-Za-z0-9_-]+\z/.freeze
+
     # Field name -> a JSON path. Dotted names address nested keys.
+    #
+    # tina4: ADR-0069 - this is the single chokepoint every field path passes
+    # through on its way into SQL (extract / json_type / json_each, so filters
+    # at any depth, operator fields and sort keys). Every dot-separated segment
+    # must match [A-Za-z0-9_-]+ or the path is rejected before any SQL is built.
     def json_path(field)
-      segments = field.to_s.split(".").map do |s|
-        s.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/) ? s : "\"#{s}\""
+      path = field.to_s
+      segments = path.split(".", -1)
+      if segments.empty? || !segments.all? { |segment| segment.match?(FIELD_SEGMENT_RE) }
+        raise ArgumentError,
+              "DocStore: invalid field path '#{path}' - each dot-separated segment must match [A-Za-z0-9_-]+"
       end
-      "$." + segments.join(".")
+
+      quoted = segments.map { |segment| segment.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/) ? segment : "\"#{segment}\"" }
+      "$." + quoted.join(".")
     end
 
     def extract(field) = "json_extract(doc, '#{json_path(field)}')"
@@ -813,7 +832,7 @@ module Tina4
 
       def initialize(path = nil)
         @path = path || ENV["TINA4_DOC_STORE_PATH"] || "data/tina4_docstore.db"
-        require "sqlite3"
+        Tina4.require_sqlite3!
         if @path != ":memory:"
           dir = File.dirname(@path)
           require "fileutils"

data/lib/tina4/drivers/arango_graph_driver.rb

@@ -1,4 +1,10 @@
 # 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/.
+
 
 # ArangoDB graph adapter — the document/AQL engine behind the same surface.
 #
@@ -18,6 +24,7 @@
 require "net/http"
 require "json"
 require "uri"
+require_relative "../parse_json"
 
 module Tina4
   module Drivers
@@ -221,7 +228,7 @@ module Tina4
       end
 
       def parse_response(response)
-        parsed = response.body && !response.body.empty? ? JSON.parse(response.body) : {}
+        parsed = response.body && !response.body.empty? ? Tina4.parse_json(response.body) : {}
         code = response.code.to_i
         if code >= 400 || parsed["error"] == true
           message = parsed["errorMessage"] || parsed["error"] || "HTTP #{response.code}"

data/lib/tina4/drivers/bolt_graph_driver.rb

@@ -1,4 +1,10 @@
 # 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/.
+
 
 # Bolt graph adapter — Neo4j AND Memgraph (both speak Bolt + Cypher).
 #

data/lib/tina4/drivers/firebird_driver.rb

@@ -1,3 +1,9 @@
+# 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/.
+
 require "set"
 # frozen_string_literal: true
 
@@ -7,6 +13,15 @@ module Tina4
       include Tina4::DatabaseAdapter
       attr_reader :connection
 
+      # Raised when a statement that returns values from a WRITE
+      # (INSERT/UPDATE/DELETE ... RETURNING, or EXECUTE PROCEDURE with outputs)
+      # is read through fetch/fetch_one. See #execute_query.
+      class ReturningNotSupported < StandardError; end
+
+      # The `fb` gem's error for a fetch from a cursor Firebird never opened
+      # (SQLCODE -504) - what a singleton RETURNING result produces.
+      CURSOR_NOT_OPEN_MARKERS = ["cursor is not open", "unknown cursor"].freeze
+
       # Substring markers (lowercased) that identify a dead-socket Firebird
       # error worth reconnecting for. Idle Firebird connections die silently
       # behind NAT timeouts, server-side ConnectionIdleTimeout, or Docker
@@ -219,14 +234,45 @@ module Tina4
         @connection&.close
       end
 
+      # Run a statement that returns rows and hydrate them.
+      #
+      # The cursor is driven HERE rather than through Connection#query so that a
+      # failed fetch can be cleaned up. Connection#query (and #execute) start an
+      # AUTOMATIC transaction when none is open and end it only when the cursor
+      # is closed after a SUCCESSFUL fetch - and closing it COMMITS. A fetch that
+      # raised used to skip all of that: the automatic transaction, holding any
+      # write the statement made, stayed open on the connection, every later
+      # statement ran inside it, and DDL on the table blocked ("object in use").
+      #
+      # The one statement that always fails that way is a write that returns
+      # values - INSERT/UPDATE/DELETE ... RETURNING. Firebird runs it as an
+      # EXECUTE PROCEDURE-type statement whose values come back only through
+      # isc_dsql_execute2's OUTPUT sqlda, which the `fb` gem never passes: it
+      # opens no cursor and the first fetch raises "Cursor is not open" (-504).
+      # There is no other call in the gem that returns them (measured, fb 0.10.0
+      # on Firebird 5), so it is refused with a clear ReturningNotSupported.
+      #
+      # On ANY fetch failure: outside an explicit transaction the automatic one
+      # is ROLLED BACK first (nothing is written, nothing stays locked, and the
+      # cursor's close can no longer commit it); inside an explicit transaction
+      # it is left for the caller's own rollback. The cursor is then dropped so
+      # its prepared statement does not hold the table.
       def execute_query(sql, params = [])
-        rows = with_reconnect do
-          if params.empty?
-            @connection.query(:hash, sql)
-          else
-            @connection.query(:hash, sql, *params)
-          end
+        cursor = with_reconnect do
+          params.empty? ? @connection.execute(sql) : @connection.execute(sql, *params)
+        end
+        # A statement with no result set: execute already ran (and, outside a
+        # transaction, committed) it and returned a count.
+        return [] unless cursor.respond_to?(:fetchall)
+
+        rows = begin
+          cursor.fetchall(:hash)
+        rescue StandardError => e
+          abandon_cursor(cursor)
+          raise returning_not_supported if cursor_not_open?(e)
+          raise
         end
+        cursor.close
         rows.map { |row| decode_blobs(symbolize_keys(row)) }
       end
 
@@ -438,6 +484,49 @@ module Tina4
         yield
       end
 
+      # Clean up after a fetch that raised: roll back the AUTOMATIC transaction
+      # (never an explicit one - that is the caller's) BEFORE the cursor is
+      # released, then free the cursor's prepared statement.
+      #
+      # Cursor#close, not #drop: #drop raises on the DSQL_close of a cursor
+      # Firebird never opened and so never reaches DSQL_drop, leaving the
+      # statement - and the table - held until GC ("object in use" on DDL).
+      # #close only warns on that step and always drops. It commits only the
+      # cursor's OWN automatic transaction, which is already rolled back here
+      # (the handle no longer matches), and never an explicit one.
+      def abandon_cursor(cursor)
+        begin
+          @connection.rollback if !@in_transaction && @connection.transaction_started
+        rescue StandardError
+          nil # the original error is the one worth reporting
+        end
+        begin
+          cursor.close
+        rescue StandardError
+          nil
+        end
+      end
+
+      def cursor_not_open?(error)
+        message = error.message.to_s.downcase
+        CURSOR_NOT_OPEN_MARKERS.any? { |marker| message.include?(marker) }
+      end
+
+      def returning_not_supported
+        outcome = if @in_transaction
+                    "It ran inside your explicit transaction, which is still open: roll it back."
+                  else
+                    "The statement was rolled back: nothing was written and no transaction is left open."
+                  end
+        ReturningNotSupported.new(
+          "Firebird: a write that returns values (INSERT/UPDATE/DELETE ... RETURNING, or " \
+          "EXECUTE PROCEDURE with outputs) cannot be read back through the `fb` gem - it never " \
+          "opens a cursor for a singleton result. #{outcome} Run the write without RETURNING " \
+          "and read the row back with a SELECT, use db.insert(...), or write it as " \
+          "INSERT ... SELECT ... RETURNING, which Firebird returns as a real cursor."
+        )
+      end
+
       # Hydrate a raw fb-gem row into a SYMBOL-keyed Hash — parity with the
       # sqlite/postgres/mssql drivers (SqliteDriver#symbolize_rows,
       # PostgresDriver#symbolize_result, MssqlDriver's `symbolize_keys: true`),

data/lib/tina4/drivers/mongodb_driver.rb

@@ -1,4 +1,10 @@
 # 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
   module Drivers

data/lib/tina4/drivers/mssql_driver.rb

@@ -1,4 +1,10 @@
 # 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/.
+
 
 require_relative "schema_split"
 
@@ -225,49 +231,58 @@ module Tina4
         end
       end
 
+      # tiny_tds has no parameter binding, so each PLACEHOLDER `?` is replaced by
+      # its escaped value in ONE pass over the SQL (python #138). This used to
+      # `sub` the first `?` once per param, so a `?` inside a string literal, a
+      # [bracketed] or "quoted" identifier or a comment took a value, and so did
+      # a `?` inside a value spliced in by the previous param ("a?b" then 2 gave
+      # 'a2b' and left a placeholder behind). A `?` beyond the params is left as
+      # it was.
       def interpolate_params(sql, params)
         return sql if params.empty?
-        result = sql.dup
-        params.each do |param|
-          escaped =
-            if param.nil?
-              "NULL"
-            elsif param == true
-              # SQL Server has no boolean literal — BIT stores 0/1. A raw `true`
-              # would interpolate as the bareword `true` ("Invalid column name
-              # 'true'"). Coerce at the bind boundary, parity with the SQLite
-              # driver's coerce_params and the Python/PHP/Node bind contract.
-              "1"
-            elsif param == false
-              "0"
-            elsif param.is_a?(Time) || param.is_a?(DateTime)
-              "'#{(param.respond_to?(:iso8601) ? param.iso8601 : param.to_s).gsub("'", "''")}'"
-            elsif param.is_a?(String)
-              interpolate_string(param)
-            elsif param.is_a?(Integer)
-              param.to_s
-            elsif param.is_a?(Float)
-              # A finite Float is a valid numeric literal; NaN/Infinity are not
-              # representable in T-SQL and would stringify to a bareword.
-              raise ArgumentError, "MssqlDriver cannot bind a non-finite Float (#{param})" unless param.finite?
 
-              param.to_s
-            elsif param.is_a?(Numeric)
-              # BigDecimal / Rational -> a plain decimal literal.
-              param.to_s
-            else
-              # MSSQL-INTERP-RUBY: the old `else param.to_s` emitted a BAREWORD for
-              # any unrecognised type (a Symbol became `WHERE x = active`, invalid
-              # or unintended SQL - a breakage / injection vector). Refuse it loudly
-              # instead of splicing an arbitrary object's #to_s into the statement.
-              raise ArgumentError,
-                    "MssqlDriver cannot safely bind a #{param.class} parameter to MSSQL " \
-                    "(#{param.inspect}); pass nil, true/false, a Time, a String " \
-                    "(text, or ASCII-8BIT bytes), or a Numeric - never a bareword"
-            end
-          result = result.sub("?", escaped)
+        Tina4::SQLTranslator.replace_placeholders(sql, brackets: true) do |index|
+          index < params.length ? sql_literal(params[index]) : "?"
+        end
+      end
+
+      # One parameter as a T-SQL literal.
+      def sql_literal(param)
+        if param.nil?
+          "NULL"
+        elsif param == true
+          # SQL Server has no boolean literal — BIT stores 0/1. A raw `true`
+          # would interpolate as the bareword `true` ("Invalid column name
+          # 'true'"). Coerce at the bind boundary, parity with the SQLite
+          # driver's coerce_params and the Python/PHP/Node bind contract.
+          "1"
+        elsif param == false
+          "0"
+        elsif param.is_a?(Time) || param.is_a?(DateTime)
+          "'#{(param.respond_to?(:iso8601) ? param.iso8601 : param.to_s).gsub("'", "''")}'"
+        elsif param.is_a?(String)
+          interpolate_string(param)
+        elsif param.is_a?(Integer)
+          param.to_s
+        elsif param.is_a?(Float)
+          # A finite Float is a valid numeric literal; NaN/Infinity are not
+          # representable in T-SQL and would stringify to a bareword.
+          raise ArgumentError, "MssqlDriver cannot bind a non-finite Float (#{param})" unless param.finite?
+
+          param.to_s
+        elsif param.is_a?(Numeric)
+          # BigDecimal / Rational -> a plain decimal literal.
+          param.to_s
+        else
+          # MSSQL-INTERP-RUBY: the old `else param.to_s` emitted a BAREWORD for
+          # any unrecognised type (a Symbol became `WHERE x = active`, invalid
+          # or unintended SQL - a breakage / injection vector). Refuse it loudly
+          # instead of splicing an arbitrary object's #to_s into the statement.
+          raise ArgumentError,
+                "MssqlDriver cannot safely bind a #{param.class} parameter to MSSQL " \
+                "(#{param.inspect}); pass nil, true/false, a Time, a String " \
+                "(text, or ASCII-8BIT bytes), or a Numeric - never a bareword"
         end
-        result
       end
 
       # Bind a String parameter. ASCII-8BIT (binary) bytes become a T-SQL

data/lib/tina4/drivers/mysql_driver.rb

@@ -1,4 +1,10 @@
 # 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/.
+
 
 require_relative "schema_split"
 require_relative "../sql_translator"

data/lib/tina4/drivers/odbc_driver.rb

@@ -1,4 +1,10 @@
 # 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
   module Drivers

data/lib/tina4/drivers/postgres_driver.rb

@@ -1,4 +1,10 @@
 # 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/.
+
 
 require_relative "schema_split"
 
@@ -59,11 +65,10 @@ module Tina4
       end
 
       def execute_query(sql, params = [])
-        converted_sql = convert_placeholders(sql)
         result = if params.empty?
-                   @connection.exec(converted_sql)
+                   @connection.exec(sql) # no params: sent exactly as written
                  else
-                   @connection.exec_params(converted_sql, params)
+                   @connection.exec_params(convert_placeholders(sql), params)
                  end
         track_affected(result)
         symbolize_result(result)
@@ -77,11 +82,10 @@ module Tina4
         # Clear the cache so last_insert_id falls back to the lastval() probe,
         # which is the correct source for a sequence-backed bare INSERT.
         @last_returning_id = nil if sql.lstrip[0, 6].upcase == "INSERT"
-        converted_sql = convert_placeholders(sql)
         result = if params.empty?
-                   @connection.exec(converted_sql)
+                   @connection.exec(sql) # no params: sent exactly as written
                  else
-                   @connection.exec_params(converted_sql, params)
+                   @connection.exec_params(convert_placeholders(sql), params)
                  end
         track_affected(result)
         result
@@ -127,6 +131,7 @@ module Tina4
         result = execute_query(sql, data.values)
         row = result.is_a?(Array) ? result.first : nil
         id = normalize_returned_id(row)
+        id = sequence_value_in(row) if id.nil? && row.is_a?(Hash)
         # Remember the real id so a follow-up #last_insert_id / db.get_last_id
         # surfaces THIS value (incl. a UUID string) instead of re-probing
         # lastval(), which has no sequence for a UUID PK and would return a
@@ -326,6 +331,18 @@ module Tina4
         end
       end
 
+      # A key column not named ``id`` (``person_id SERIAL``) is invisible to
+      # row_id_value, so ask the sequence. lastval() is session-wide: on a table
+      # with no sequence it is a value from some EARLIER insert, so it is only
+      # trusted when the row this INSERT returned actually holds it.
+      def sequence_value_in(row)
+        @last_returning_id = nil
+        value = last_insert_id
+        return nil if value.nil?
+
+        row.values.any? { |column_value| column_value.to_s == value.to_s } ? value : nil
+      end
+
       # Read the ``id`` column from a RETURNING row regardless of key style
       # (symbol/string, any case) — execute_query symbolizes keys, but stay
       # tolerant.
@@ -384,9 +401,19 @@ module Tina4
         end
       end
 
+      # ? -> $1, $2 ... for every PLACEHOLDER only: a `?` inside a string
+      # literal (incl. E'...' and $$...$$), a quoted identifier or a comment is
+      # left alone (python #138). This was a plain gsub, so
+      # SELECT 'why?', ? became SELECT 'why$1', $2 and failed.
+      #
+      # Called ONLY when there are parameters to bind. SQL with no parameters is
+      # sent exactly as written (the cross-framework contract), so the jsonb
+      # operators ?, ?| and ?& work in a parameterless query.
+      # tina4: with parameters, use jsonb_exists(), jsonb_exists_any() or
+      # jsonb_exists_all() instead of ?, ?| or ?& - here every bare `?` is a
+      # placeholder.
       def convert_placeholders(sql)
-        counter = 0
-        sql.gsub("?") { counter += 1; "$#{counter}" }
+        Tina4::SQLTranslator.replace_placeholders(sql) { |index| "$#{index + 1}" }
       end
 
       # Hydrate a PG::Result into an array of symbol-keyed row hashes.

data/lib/tina4/drivers/schema_split.rb

@@ -1,4 +1,10 @@
 # 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
   module Drivers

data/lib/tina4/drivers/sqlite_driver.rb

@@ -1,6 +1,13 @@
 # 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/.
+
 
 require_relative "schema_split"
+require_relative "../sqlite3_gem"
 
 module Tina4
   module Drivers
@@ -27,7 +34,7 @@ module Tina4
       # hang. Every other driver's bound lives in its own connect; this is the
       # one that has nothing to bind.
       def connect(connection_string, username: nil, password: nil)
-        require "sqlite3"
+        Tina4.require_sqlite3!
         db_path = self.class.resolve_path(connection_string)
 
         @connection = SQLite3::Database.new(db_path)

data/lib/tina4/drivers/ultipa_graph_driver.rb

@@ -1,4 +1,10 @@
 # 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/.
+
 
 # Ultipa graph adapter — the portable core built in GQL over tina4-ultipa.
 #