tina4ruby 3.13.94 → 3.13.97

data/lib/tina4/docstore.rb

@@ -46,12 +46,21 @@
 require "json"
 require "time"
 require "securerandom"
+require "delegate"
 
 module Tina4
   module DocStore
     # Raised when a value cannot be parsed as an ObjectId.
     class InvalidId < ArgumentError; end
 
+    # A Mongo URI is configured but the MongoDB driver is not installed.
+    #
+    # ADR-0024 rule 3, settled for DocStore by ADR-0033: a provider that cannot
+    # honour an operation must RAISE, naming the provider and what is missing.
+    # Falling back to the local SQLite store here would send production writes
+    # to a container-local file nobody reads.
+    class DocStoreDriverMissing < StandardError; end
+
     OID_RE = /\A[0-9a-fA-F]{24}\z/.freeze
     ISO_RE = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})?\z/.freeze
 
@@ -193,6 +202,45 @@ module Tina4
 
     def json_type(field) = "json_type(doc, '#{json_path(field)}')"
 
+    # A rowset over the field: one row per element of an array, one for a scalar.
+    def json_each(field) = "json_each(doc, '#{json_path(field)}')"
+
+    # True when the field is an ARRAY and any element satisfies +condition+.
+    #
+    # MongoDB's rule for an array-valued field is that a condition matches when
+    # ANY ELEMENT matches it. json_each yields one row per element, so EXISTS is
+    # the direct translation.
+    #
+    # The `= 'array'` guard is load-bearing: json_each over an OBJECT iterates
+    # its VALUES, and Mongo never matches an object field against one of its
+    # values - {"obj" => "x"} must NOT match {"obj" => {"city" => "x"}}.
+    def any_element(field, condition)
+      "(#{json_type(field)} = 'array' AND EXISTS (SELECT 1 FROM #{json_each(field)} WHERE #{condition}))"
+    end
+
+    # Compile `field == operand` under Mongo's array rule -> [sql, params].
+    def equality(field, operand)
+      ex = extract(field)
+      return ["#{ex} IS NULL", []] if operand.nil?
+
+      # An Array or Hash operand compares against the WHOLE value, never
+      # element-wise: {"tags" => ["x","y"]} is exact-array equality.
+      return ["#{ex} = ?", [bind(operand)]] if operand.is_a?(Array) || operand.is_a?(Hash)
+
+      ["(#{ex} = ? OR #{any_element(field, "value = ?")})", [bind(operand), bind(operand)]]
+    end
+
+    # Compile `field OP operand` under Mongo's array rule -> [sql, params].
+    #
+    # The `<> 'array'` guard on the scalar branch removes a measured FALSE
+    # POSITIVE: json_extract of an array returns its JSON TEXT, and SQLite sorts
+    # any text above any number, so {"nums" => {"$gt" => 9}} matched [1,2,3].
+    def compare(field, sql_op, operand)
+      ex = extract(field)
+      ["((#{json_type(field)} <> 'array' AND #{ex} #{sql_op} ?) OR #{any_element(field, "value #{sql_op} ?")})",
+       [bind(operand), bind(operand)]]
+    end
+
     # Compile a Mongo-style filter Hash into [sql_fragment, params].
     # Returns ["1=1", []] for an empty filter. Supports implicit AND across keys,
     # $or / $and, and the per-field operator set.
@@ -221,11 +269,12 @@ module Tina4
             clauses << frag
             params.concat(p)
           end
-        elsif value.nil?
-          clauses << "#{extract(key)} IS NULL"
         else
-          clauses << "#{extract(key)} = ?"
-          params << bind(value)
+          # equality - the same helper $eq uses, so the array rule applies
+          # whether the filter reads {"tags" => "x"} or {"tags" => {"$eq" => "x"}}
+          frag, p = equality(key, value)
+          clauses << frag
+          params.concat(p)
         end
       end
 
@@ -234,37 +283,40 @@ module Tina4
 
     def compile_op(field, op, operand)
       ex = extract(field)
-      if COMPARATORS.key?(op)
-        return ["#{ex} #{COMPARATORS[op]} ?", [bind(operand)]]
-      end
+      return compare(field, COMPARATORS[op], operand) if COMPARATORS.key?(op)
 
       case op
       when "$eq"
-        return ["#{ex} IS NULL", []] if operand.nil?
-
-        ["#{ex} = ?", [bind(operand)]]
+        equality(field, operand)
       when "$ne"
         return ["#{ex} IS NOT NULL", []] if operand.nil?
 
-        ["(#{ex} <> ? OR #{ex} IS NULL)", [bind(operand)]]
+        sql, p = equality(field, operand)
+        # A MISSING field satisfies $ne in Mongo, and SQL's NOT(NULL) is NULL
+        # rather than true - so the IS NULL arm is required, not decoration.
+        ["(NOT (#{sql}) OR #{ex} IS NULL)", p]
       when "$in"
         items = Array(operand)
         return ["0", []] if items.empty?
 
         placeholders = (["?"] * items.length).join(",")
-        ["#{ex} IN (#{placeholders})", items.map { |v| bind(v) }]
+        bound = items.map { |v| bind(v) }
+        ["(#{ex} IN (#{placeholders}) OR #{any_element(field, "value IN (#{placeholders})")})", bound + bound]
       when "$nin"
         items = Array(operand)
         return ["1", []] if items.empty?
 
         placeholders = (["?"] * items.length).join(",")
-        ["(#{ex} NOT IN (#{placeholders}) OR #{ex} IS NULL)", items.map { |v| bind(v) }]
+        bound = items.map { |v| bind(v) }
+        ["(NOT (#{ex} IN (#{placeholders}) OR #{any_element(field, "value IN (#{placeholders})")}) OR #{ex} IS NULL)",
+         bound + bound]
       when "$exists"
         # json_type is NULL when the path is absent; present-but-null still has a type.
         [operand ? "#{json_type(field)} IS NOT NULL" : "#{json_type(field)} IS NULL", []]
       when "$regex"
         pattern = operand.is_a?(Hash) ? operand["$regex"].to_s : operand.to_s
-        ["#{ex} REGEXP ?", [pattern]]
+        ["((#{json_type(field)} <> 'array' AND #{ex} REGEXP ?) OR #{any_element(field, "value REGEXP ?")})",
+         [pattern, pattern]]
       else
         raise ArgumentError, "DocStore: unsupported query operator #{op.inspect}"
       end
@@ -292,8 +344,37 @@ module Tina4
       end
     end
 
+    # Normalise the driver's three sort spellings to an array of [key, direction].
+    #
+    # ADR-0036. Mongo::Collection::View#sort takes ONE spec document; the
+    # framework documents sort(key, direction); and a list of pairs is the third
+    # form pymongo and the Node driver both take. Measured 2026-08-04 against a
+    # real MongoDB, ALL THREE had to work on both providers before one spelling
+    # could be called portable: the two-argument form raised ArgumentError on
+    # the Ruby driver, and the pairs form reached the server as an ARRAY and
+    # came back "[14:TypeMismatch]: Expected field sort to be of type object".
+    def sort_spec(key_or_list, direction = 1)
+      case key_or_list
+      when String, Symbol then [[key_or_list.to_s, direction]]
+      else key_or_list.map { |key, sort_direction| [key.to_s, sort_direction] }
+      end
+    end
+
     # -- Projection / update helpers --------------------------------------------
 
+    # Decode a stored JSON document, rehydrating ObjectId and Time values.
+    #
+    # Module-level because it is a PURE function of its inputs. It was a public
+    # collection method only so the Cursor could reach it, which ADR-0025
+    # corollary 1 forbids.
+    def load_doc(doc_text, projection = nil)
+      doc = decode_value(JSON.parse(doc_text))
+      projection ? project(doc, projection) : doc
+    end
+
+    # Encode a document for storage. Pure, for the same reason as load_doc.
+    def dump_doc(document) = JSON.generate(encode_value(document))
+
     def project(doc, projection)
       return doc if projection.nil? || projection.empty?
 
@@ -392,8 +473,15 @@ module Tina4
     class Cursor
       include Enumerable
 
-      def initialize(collection, where, params, projection = nil)
-        @collection = collection
+      # The cursor receives WHAT IT NEEDS, not the collection it came from.
+      #
+      # It used to hold the collection and reach back into it for quoted_name,
+      # connection and load_doc - which was the ONLY reason those three were
+      # public. ADR-0025 corollary 1: anything the fallback needs internally is
+      # private, and a real Mongo::Collection::View exposes none of them.
+      def initialize(conn, quoted_name, where, params, projection = nil)
+        @conn = conn
+        @quoted_name = quoted_name
         @where = where
         @params = params
         @projection = projection
@@ -403,11 +491,7 @@ module Tina4
       end
 
       def sort(key_or_list, direction = 1)
-        if key_or_list.is_a?(String) || key_or_list.is_a?(Symbol)
-          @sort << [key_or_list.to_s, direction]
-        else
-          key_or_list.each { |k, d| @sort << [k.to_s, d] }
-        end
+        @sort.concat(DocStore.sort_spec(key_or_list, direction))
         self
       end
 
@@ -422,7 +506,7 @@ module Tina4
       end
 
       def build_sql
-        sql = "SELECT doc FROM #{@collection.quoted_name} WHERE #{@where}"
+        sql = "SELECT doc FROM #{@quoted_name} WHERE #{@where}"
         unless @sort.empty?
           order = @sort.map { |k, d| "#{DocStore.extract(k)} #{d.to_i.negative? ? 'DESC' : 'ASC'}" }.join(", ")
           sql += " ORDER BY #{order}"
@@ -439,9 +523,9 @@ module Tina4
       def each
         return enum_for(:each) unless block_given?
 
-        @collection.connection.execute(build_sql, @params).each do |row|
+        @conn.execute(build_sql, @params).each do |row|
           doc_text = row.is_a?(Hash) ? (row["doc"] || row[:doc] || row.values.first) : row.first
-          yield @collection.load_doc(doc_text, @projection)
+          yield DocStore.load_doc(doc_text, @projection)
         end
       end
 
@@ -450,15 +534,26 @@ module Tina4
         each { |doc| out << doc }
         out
       end
-      alias to_list to_a
+
+      # The uniform Tina4 spelling, ADDITIVE to to_a (ADR-0035).
+      #
+      # ADR-0025 corollary 1 removed this because Mongo::Collection::View has no
+      # to_list. ADR-0035 amends that corollary: a method may exist here when it
+      # also exists on WHAT get_collection RETURNS for the real provider, and
+      # MongoView supplies it there. to_a stays - it is the driver's spelling
+      # and the Ruby idiom - so both work on both providers.
+      def to_list = to_a
+
+      # The generated SQL is an implementation detail, not part of the cursor
+      # API. Declared here rather than with a `private` section because build_sql
+      # is defined above and a trailing `private` would not reach it.
+      private :build_sql
     end
 
     # -- Collection -------------------------------------------------------------
 
     # A SQLite-backed collection exposing the everyday Mongo API.
     class SqliteCollection
-      attr_reader :connection
-
       def initialize(conn, name)
         @connection = conn
         @name = name.to_s
@@ -470,23 +565,13 @@ module Tina4
         )
       end
 
-      def quoted_name = @quoted_name
-
-      # -- helpers --
-      def dump(document) = JSON.generate(DocStore.encode_value(document))
-
-      def load_doc(doc_text, projection = nil)
-        doc = DocStore.decode_value(JSON.parse(doc_text))
-        projection ? DocStore.project(doc, projection) : doc
-      end
-
       # -- writes --
       def insert_one(document)
         doc = stringify(document)
         doc["_id"] = ObjectId.new unless doc.key?("_id")
         @connection.execute(
           "INSERT INTO #{@quoted_name} (_id, doc) VALUES (?, ?)",
-          [DocStore.id_key(doc["_id"]), dump(doc)]
+          [DocStore.id_key(doc["_id"]), DocStore.dump_doc(doc)]
         )
         InsertOneResult.new(doc["_id"])
       end
@@ -499,7 +584,7 @@ module Tina4
           ids << doc["_id"]
           @connection.execute(
             "INSERT INTO #{@quoted_name} (_id, doc) VALUES (?, ?)",
-            [DocStore.id_key(doc["_id"]), dump(doc)]
+            [DocStore.id_key(doc["_id"]), DocStore.dump_doc(doc)]
           )
         end
         InsertManyResult.new(ids)
@@ -508,11 +593,18 @@ module Tina4
       # -- reads --
       def find(filter = nil, projection = nil)
         where, params = DocStore.compile_filter(filter || {})
-        Cursor.new(self, where, params, projection)
+        Cursor.new(@connection, @quoted_name, where, params, projection)
       end
 
+      # The uniform Tina4 spelling, ADDITIVE to find(filter).first (ADR-0035).
+      #
+      # Mongo::Collection has no find_one, which is why ADR-0025 corollary 1
+      # deleted this. ADR-0035 amends the means, not the goal: MongoCollection
+      # supplies find_one on the driver side, so the method now exists with the
+      # same meaning on BOTH halves of the swap. The signature is pymongo's,
+      # which is what the Python master already ships.
       def find_one(filter = nil, projection = nil)
-        find(filter, projection).limit(1).to_a.first
+        find(filter, projection).first
       end
 
       def count_documents(filter = nil)
@@ -626,7 +718,7 @@ module Tina4
         new_key = DocStore.id_key(new_doc["_id"])
         @connection.execute(
           "UPDATE #{@quoted_name} SET _id = ?, doc = ? WHERE _id = ?",
-          [new_key, dump(new_doc), old_id]
+          [new_key, DocStore.dump_doc(new_doc), old_id]
         )
         true
       end
@@ -652,6 +744,67 @@ module Tina4
       end
     end
 
+    # -- The driver delegators (ADR-0035) -----------------------------------------
+    #
+    # ADR-0025 costed "wrap the driver" as a hand-written FACADE over 12-14
+    # methods, and rejected it because that makes aggregate, bulk_write,
+    # indexes, watch, sessions and transactions unreachable. That objection is
+    # fatal to a facade and irrelevant to a DELEGATOR: SimpleDelegator forwards
+    # EVERYTHING untouched, so the entire driver surface stays reachable and we
+    # add exactly one method per class.
+    #
+    # These exist so the uniform Tina4 spelling works on BOTH providers rather
+    # than on the fallback alone - which is the thing ADR-0025 corollary 1 was
+    # right to forbid, and ADR-0035 supplies instead of deleting.
+
+    # A Mongo::Collection::View that also answers to_list, and accepts every
+    # sort spelling the fallback Cursor accepts.
+    class MongoView < SimpleDelegator
+      # to_a is the driver's spelling and stays authoritative; to_list is the
+      # uniform Tina4 spelling the SQLite Cursor also answers.
+      def to_list = __getobj__.to_a
+
+      # ADR-0036: ONE sort contract on both providers.
+      #
+      # Mongo::Collection::View#sort takes a single spec document, so
+      # sort("total", -1) raised ArgumentError and sort([["total", -1]]) reached
+      # the server as an array and came back TypeMismatch. Normalising here means
+      # all three spellings work on the driver exactly as they do on the
+      # fallback - which is the point of the swap.
+      def sort(key_or_list, direction = 1)
+        MongoView.new(__getobj__.sort(DocStore.sort_spec(key_or_list, direction).to_h))
+      end
+
+      # A View is IMMUTABLE - sort/limit/skip/projection each return a NEW View.
+      # Without re-wrapping, the first chained call would hand back a bare View
+      # and to_list would vanish mid-chain: exactly the "works until you sort
+      # it" surprise this ADR exists to stop.
+      def method_missing(name, *args, &block)
+        result = super
+        result.is_a?(::Mongo::Collection::View) ? MongoView.new(result) : result
+      end
+      ruby2_keywords :method_missing
+    end
+
+    # A Mongo::Collection that also answers find_one, and whose find returns a
+    # cursor answering to_list.
+    class MongoCollection < SimpleDelegator
+      # Pure pass-through plus wrapping. The argument list is NOT re-declared,
+      # so the driver keeps deciding what find accepts.
+      def find(*args, &block)
+        MongoView.new(__getobj__.find(*args, &block))
+      end
+      ruby2_keywords :find
+
+      # pymongo's signature, which the Python master already ships. On the
+      # driver a projection is an OPTION rather than a positional, so it is
+      # spelled the driver's way here; the meaning is identical.
+      def find_one(filter = nil, projection = nil)
+        view = projection ? __getobj__.find(filter || {}, projection: projection) : __getobj__.find(filter || {})
+        view.first
+      end
+    end
+
     # -- Database + selection -----------------------------------------------------
 
     # A SQLite-backed document database (a file of collection tables).
@@ -694,27 +847,35 @@ module Tina4
 
     module_function
 
+    # The env var that supplied the URI, or nil when none did.
+    #
+    # Named separately so an error can tell the operator WHICH variable to
+    # unset without ever printing its value - a Mongo URI routinely carries
+    # `user:password@`.
+    #
+    # Canonical TINA4_MONGO_URI, then the session-layer TINA4_SESSION_MONGO_URI;
+    # TINA4_SESSION_MONGO_URL is a legacy alias.
+    def mongo_uri_source
+      %w[TINA4_MONGO_URI TINA4_SESSION_MONGO_URI TINA4_SESSION_MONGO_URL]
+        .find { |name| !(ENV[name] || "").strip.empty? }
+    end
+
     # The configured Mongo URI, reusing the app-wide queue/session env vars.
-    # Canonical TINA4_SESSION_MONGO_URI; TINA4_SESSION_MONGO_URL is a legacy alias.
     def mongo_uri
-      (ENV["TINA4_MONGO_URI"] ||
-       ENV["TINA4_SESSION_MONGO_URI"] ||
-       ENV["TINA4_SESSION_MONGO_URL"] ||
-       "").strip
+      source = mongo_uri_source
+      source ? ENV[source].strip : ""
     end
 
     # True when no Mongo is configured, so the SQLite fallback is in effect.
+    #
+    # CONFIGURATION ONLY. Before 3.13.95 this also returned true when a URI was
+    # set but the mongo gem was absent, and that is precisely what made
+    # get_collection hand back the local SQLite store while the operator
+    # believed they were on Mongo. A missing driver is now an error (ADR-0033),
+    # not a second way to be serverless - otherwise an app branching on this
+    # would take the local path and never reach the raise.
     def serverless?
-      return true if mongo_uri.empty?
-
-      begin
-        require "mongo"
-        false
-      rescue LoadError
-        # A URI is set but the driver is absent: degrade to the local store
-        # rather than crash.
-        true
-      end
+      mongo_uri.empty?
     end
 
     @default_db = nil
@@ -733,13 +894,66 @@ module Tina4
     # A real Mongo driver Collection when a Mongo URI is configured (and the
     # mongo gem is installed); otherwise a SqliteCollection backed by the local
     # SQLite file. Same call sites either way - only the backend differs.
+    #
+    # The Mongo collection is handed back through MongoCollection, a
+    # SimpleDelegator that adds the uniform Tina4 spellings and forwards
+    # everything else untouched (ADR-0035). What this method RETURNS is the
+    # surface a call site sees, so it is the surface the contract compares.
     def get_collection(name)
       return default_db.get_collection(name) if serverless?
 
-      require "mongo"
       db_name = ENV["TINA4_MONGO_DB"] || ENV["TINA4_SESSION_MONGO_DB"] || "tina4"
-      client = Mongo::Client.new(mongo_uri, database: db_name)
-      client[name]
+      MongoCollection.new(mongo_client(mongo_uri, db_name)[name])
+    end
+
+    @mongo_clients = {}
+
+    # Return the shared Mongo client for this (uri, database), connecting once.
+    #
+    # MEASURED 2026-08-03 against a real MongoDB: get_collection used to build a
+    # new Mongo::Client on EVERY call and never close it, so 20 calls left 60
+    # server connections open and the count grew without bound. It was invisible
+    # in development because the SQLite fallback has no connections at all - a
+    # resource leak that only exists AFTER the swap to the real provider.
+    #
+    # A Mongo::Client is thread-safe and pools internally, so one per
+    # (uri, database) is the shape the driver itself expects. The double-checked
+    # lock matches default_db above: without it two threads racing the first call
+    # both build a client and one is orphaned - the same leak, just rarer.
+    #
+    # A missing gem raises here, at provider RESOLUTION, before any socket is
+    # opened: it is a static fact and needs no network to establish.
+    def mongo_client(uri, db_name)
+      begin
+        require "mongo"
+      rescue LoadError
+        source = mongo_uri_source || "TINA4_MONGO_URI"
+        raise DocStoreDriverMissing,
+              "Tina4 DocStore: #{source} is set, so the MongoDB provider is selected, but " \
+              "its driver is not installed (gem 'mongo'). Install it with `gem install mongo`, " \
+              "or unset #{source} to use the local SQLite store."
+      end
+      key = [uri, db_name]
+      client = @mongo_clients[key]
+      return client if client
+
+      @default_lock.synchronize do
+        @mongo_clients[key] ||= Mongo::Client.new(uri, database: db_name)
+      end
+    end
+
+    # Close every DocStore connection: the SQLite store and all Mongo clients.
+    def close_doc_store
+      @default_lock.synchronize do
+        @mongo_clients.each_value do |client|
+          client.close
+        rescue StandardError
+          nil # a close failure must not mask the caller's work
+        end
+        @mongo_clients.clear
+        @default_db&.close
+        @default_db = nil
+      end
     end
 
     # Drop the cached default SQLite store (test helper).

data/lib/tina4/drivers/firebird_driver.rb

@@ -1,8 +1,10 @@
+require "set"
 # frozen_string_literal: true
 
 module Tina4
   module Drivers
     class FirebirdDriver
+      include Tina4::DatabaseAdapter
       attr_reader :connection
 
       # Substring markers (lowercased) that identify a dead-socket Firebird
@@ -111,6 +113,55 @@ module Tina4
         url_charset || kwarg || env || "UTF8"
       end
 
+      # Bound the REACH to a Firebird server before libfbclient is handed the
+      # attach. Raises the shared connect-timeout error when the host does not
+      # answer within TINA4_DATABASE_CONNECT_TIMEOUT.
+      #
+      # Why a socket probe and not a timeout around the attach - MEASURED on
+      # Ruby 3.2.3 / Ubuntu 24.04.4 / fb 0.10.0 against a REAL TCPServer that
+      # accepts the connection and then never replies:
+      #
+      #   fb attach, no bound          WEDGED past 20s, SIGKILL needed
+      #   fb attach, Timeout.timeout(3) WEDGED past 20s - the timeout NEVER fired
+      #   fb attach, Thread#join(3)     WEDGED past 20s - join never returned
+      #
+      # The gem calls isc_attach_database (fb.c:3002) WITHOUT releasing the GVL
+      # and without an unblocking function, so no Ruby thread runs to deliver
+      # the interrupt - `timeout`'s SIGTERM could not even be delivered. It also
+      # builds its DPB from a fixed four-item set (user, password, lc_ctype,
+      # role) with no connect-timeout item. There is therefore NO in-process way
+      # to bound the attach itself, and a Timeout.timeout here would be WORSE
+      # than nothing because it would look like protection and silently not fire.
+      #
+      # What IS boundable is reaching the host at all, which is the hang
+      # operators actually hit: a dead or firewalled server swallows the SYN and
+      # the process sits there. A plain stdlib socket bounds that exactly.
+      #
+      # RESIDUAL GAP, stated plainly so this is not mistaken for full cover: if
+      # the TCP handshake SUCCEEDS and the server then never speaks the Firebird
+      # protocol, the attach is still UNBOUNDED. Ruby cannot fix that from
+      # inside this process - it needs a connect timeout in the fb gem itself.
+      #
+      # ONLY a timeout is converted. A refused connection, an unknown host or
+      # any other socket error is swallowed so libfbclient still produces its
+      # own (better) diagnosis: this probe adds a bound, it does not take over
+      # error reporting.
+      def self.bound_reachability!(host, port)
+        seconds = Tina4::DatabaseAdapter.connect_timeout_seconds
+        return if seconds.nil? || host.to_s.empty?
+
+        require "socket"
+        begin
+          Tina4::DatabaseAdapter.bounding_connect(host, port) do
+            Socket.tcp(host, port, connect_timeout: seconds, &:close)
+          end
+        rescue Tina4::DatabaseConnectionError
+          raise
+        rescue StandardError
+          nil
+        end
+      end
+
       def connect(connection_string, username: nil, password: nil, charset: nil)
         require "fb"
         require "uri"
@@ -155,6 +206,7 @@ module Tina4
         # with the gem's default charset (double-encoding). Defaults to UTF8.
         @connect_opts[:charset] = self.class.resolve_charset(connection_string, charset)
 
+        self.class.bound_reachability!(host, port)
         open_connection
       rescue LoadError
         raise LoadError,
@@ -209,8 +261,12 @@ module Tina4
         (["?"] * count).join(", ")
       end
 
+      # The closing paren goes on a NEW LINE. Inline, a trailing `-- comment` in
+      # the caller's SQL comments the paren out and the whole wrapped statement
+      # is a syntax error (the same class of bug as the LIMIT append site — see
+      # the note on Drivers::SqliteDriver#apply_limit).
       def apply_limit(sql, limit, offset = 0)
-        "SELECT FIRST #{limit} SKIP #{offset} * FROM (#{sql})"
+        "SELECT FIRST #{limit} SKIP #{offset} * FROM (#{sql}\n)"
       end
 
       # Transaction handling — mirrors the Python master's connection-level
@@ -237,6 +293,20 @@ module Tina4
         @in_transaction = true
       end
 
+      # Guarded on the CONNECTION only, deliberately - no active-transaction check
+      # is needed here.
+      #
+      # Python's adapter has the same shape and it IS a bug there: firebird-driver
+      # delegates Connection#commit to main_transaction, whose handle is nil until
+      # a statement opens one, so committing with nothing open raises
+      # "AttributeError: 'NoneType' object has no attribute 'commit'". Measured
+      # 2026-08-04 against the lab's real Firebird 5.0.4, the `fb` gem does NOT
+      # behave that way: both #commit and #rollback on a fresh connection with no
+      # open transaction return cleanly, because the driver opens one implicitly.
+      #
+      # So do not "port" Python's is_active? guard here on the strength of the
+      # shape matching - it would be dead code guarding a condition this driver
+      # cannot reach.
       def commit
         @connection&.commit
         @in_transaction = false
@@ -259,13 +329,33 @@ module Tina4
               "JOIN RDB\$FIELDS F ON RF.RDB\$FIELD_SOURCE = F.RDB\$FIELD_NAME " \
               "WHERE RF.RDB\$RELATION_NAME = ?"
         rows = execute_query(sql, [table_name.upcase])
+
+        # The primary key comes from the constraint catalogue. This used to be
+        # hardcoded `false` for every column, so primary_key(table) always
+        # answered [] on Firebird -- which silently breaks anything that
+        # introspects the key, including the filterless-write guard that lifts
+        # the PK out of `data`. Same bug the Python master carried.
+        pk_sql = "SELECT SG.RDB\$FIELD_NAME FROM RDB\$INDEX_SEGMENTS SG " \
+                 "JOIN RDB\$RELATION_CONSTRAINTS RC ON SG.RDB\$INDEX_NAME = RC.RDB\$INDEX_NAME " \
+                 "WHERE RC.RDB\$CONSTRAINT_TYPE = 'PRIMARY KEY' AND RC.RDB\$RELATION_NAME = ? " \
+                 "ORDER BY SG.RDB\$FIELD_POSITION"
+        pk_names = begin
+          execute_query(pk_sql, [table_name.upcase]).map do |r|
+            (r["RDB\$FIELD_NAME"] || r["rdb\$field_name"] || "").strip.upcase
+          end.reject(&:empty?).to_set
+        rescue StandardError
+          # A table with no primary key is not an error.
+          Set.new
+        end
+
         rows.map do |r|
+          field_name = (r["RDB\$FIELD_NAME"] || r["rdb\$field_name"] || "").strip
           {
-            name: (r["RDB\$FIELD_NAME"] || r["rdb\$field_name"] || "").strip,
+            name: field_name,
             type: r["RDB\$FIELD_TYPE"] || r["rdb\$field_type"],
             nullable: (r["RDB\$NULL_FLAG"] || r["rdb\$null_flag"]).nil?,
             default: r["RDB\$DEFAULT_SOURCE"] || r["rdb\$default_source"],
-            primary_key: false
+            primary_key: pk_names.include?(field_name.upcase)
           }
         end
       end
@@ -301,7 +391,31 @@ module Tina4
       end
 
       def stringify_keys(hash)
-        hash.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+        hash.each_with_object({}) { |(k, v), h| h[column_name(k.to_s)] = v }
+      end
+
+      # Firebird's stored column name, folded back only when it was folded.
+      #
+      # Firebird's identifier folding is ASYMMETRIC. An unquoted `AS x` is
+      # stored UPPERCASE, so the driver hands back "X" where every other engine
+      # Tina4 supports gives "x" -- PostgreSQL folds to lower, and MySQL, SQLite
+      # and MSSQL preserve what you wrote. Portable code reading row["x"] broke
+      # on Firebird alone; the live URL examples in this repo asserted row["x"]
+      # and could never have passed once they actually reached a server.
+      #
+      # A QUOTED `AS "MyCol"` is stored exactly as written, and that case is
+      # deliberate -- the caller asked for it -- so it is left alone. Folding
+      # unconditionally makes a mixed-case key unreachable, the same asymmetric
+      # trap that made table_exists? miss quoted tables.
+      #
+      # So: fold back only a name carrying no lowercase letter, the only thing
+      # unquoted folding can produce. A quoted ALL-CAPS name is genuinely
+      # indistinguishable from a folded one and is lowercased too; that
+      # ambiguity is Firebird's, and it is the one spelling this cannot
+      # round-trip.
+      def column_name(raw)
+        name = raw.strip
+        name == name.upcase ? name.downcase : name
       end
 
       # Ensure Firebird BLOB columns are proper byte strings.