tina4ruby 3.13.97 → 3.13.99

data/lib/tina4/cli.rb

@@ -2,6 +2,7 @@
 
 require "optparse"
 require "fileutils"
+require_relative "port_takeover"
 
 module Tina4
   class CLI
@@ -361,77 +362,35 @@ module Tina4
     # `tina4 serve` may still hold it. Inside a container the server IS the
     # container, so there is no stale sibling to reclaim from -- and trying is
     # actively dangerous (see #kill_process_on_port).
+    # Container detection lives in the shared takeover module now; kept as an
+    # instance method so existing callers/specs resolve it on the CLI.
     def in_container?
-      return true if File.exist?("/.dockerenv") || File.exist?("/run/.containerenv")
-
-      blob = File.read("/proc/1/cgroup")
-      blob.include?("docker") || blob.include?("containerd") || blob.include?("kubepods")
-    rescue SystemCallError
-      false
+      Tina4::PortTakeover.in_container?
     end
 
-    # Kill any process listening on `port`. Returns true if anything was killed.
-    #
-    # Every PID is validated before use. `pid.to_i` on a non-numeric field
-    # yields 0, and Process.kill("TERM", 0) signals EVERY process in the
-    # caller's own process group -- the server kills itself. That is exactly
-    # what happened in a container: "Killed existing process on port 7148
-    # (PID: 1 ...)" followed by exit 143.
-    #
-    # So: skip entirely in a container, accept only all-digit PIDs, and never
-    # signal 0 (our process group), 1 (init), or ourselves.
-    # The PIDs from `lsof -ti` output that are safe to signal.
-    #
-    # Pure so the safety rule can be tested directly. An unvalidated parse is a
-    # footgun with real teeth: where lsof prints a different shape than -ti
-    # implies, a non-numeric field becomes 0, and signalling PID 0 hits EVERY
-    # process in the caller's own process group -- the server kills itself.
-    #
-    # Accept only all-digit tokens; never PID 0 (our group), PID 1 (init),
-    # ourselves, or our own process group.
+    # Thin wrapper over the shared Tina4::PortTakeover.selectable_pids so the CLI
+    # and the runtime bind-failure path share ONE implementation.
     def selectable_pids(lsof_output, me, my_group = nil)
-      pids = []
-      lsof_output.split(/\s+/).each do |token|
-        next unless token.match?(/\A\d+\z/)   # never coerce junk into a PID
-
-        pid = token.to_i
-        next if pid <= 1 || pid == me           # 0 = our group, 1 = init, me = suicide
-        next if !my_group.nil? && pid == my_group
-
-        pids << pid unless pids.include?(pid)
-      end
-      pids
+      Tina4::PortTakeover.selectable_pids(lsof_output, me, my_group)
     end
 
+    # Reclaim `port` from a stale Tina4 dev server, only when it is safe.
+    #
+    # Routes through the shared identity-checked takeover (TAKEOVER-DEC-01/02): a
+    # holder is signalled ONLY when a Tina4 dev server recorded its PID in the
+    # per-port PID file. A foreign holder is left running and a clear message is
+    # printed; takeover is also skipped in a container, outside dev mode, and when
+    # opted out (TINA4_NO_TAKEOVER / --no-kill). Returns true only when a Tina4
+    # holder was actually signalled.
     def kill_process_on_port(port)
-      return false if in_container?
-
-      result = `lsof -ti :#{port} 2>/dev/null`.strip
-      return false if result.empty?
-
-      me = Process.pid
-      my_group = begin
-        Process.getpgrp
-      rescue StandardError
-        nil
-      end
-
-      killed = []
-      selectable_pids(result, me, my_group).each do |pid|
-        begin
-          Process.kill("TERM", pid)
-          killed << pid.to_s
-        rescue Errno::ESRCH, Errno::EPERM
-          # Process already gone or no permission
-        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 true
       end
-
-      return false if killed.empty?
-
-      sleep 0.5
-      puts "  Killed existing process on port #{port} (PID: #{killed.join(', ')})"
-      true
-    rescue Errno::ENOENT
+      puts "  #{result.message}" if result.refused? && !result.message.empty?
       false
     end
 
@@ -485,6 +444,7 @@ module Tina4
         opts.on("--production", "Use production server (Puma)") { options[:production] = true }
         opts.on("--no-browser", "Do not open browser on start") { options[:no_browser] = true }
         opts.on("--no-reload", "Disable file watcher / live-reload") { options[:no_reload] = true }
+        opts.on("--no-kill", "Never take over the port from a stale dev server") { options[:no_kill] = true }
       end
       parser.parse!(argv)
 
@@ -499,6 +459,11 @@ module Tina4
         ENV["TINA4_NO_RELOAD"] = "true"
       end
 
+      # --no-kill opts out of port takeover for the whole process, so the CLI
+      # path here AND the runtime bind-failure fallback both honour it
+      # (TAKEOVER-DEC-03).
+      ENV["TINA4_NO_TAKEOVER"] = "true" if options[:no_kill]
+
       # Priority: CLI flag > ENV var > default
       options[:port] = resolve_config(:port, options[:port])
       options[:host] = resolve_config(:host, options[:host])
@@ -1337,8 +1302,8 @@ module Tina4
 
           # List all #{route_path} with pagination — public read (GET is ungated).
           Tina4::Router.get "/api/#{route_path}" do |request, response|
-            page = (request.params["page"] || 1).to_i
-            per_page = (request.params["per_page"] || 20).to_i
+            page = (request.query["page"] || 1).to_i
+            per_page = (request.query["per_page"] || 20).to_i
             offset = (page - 1) * per_page
             records = #{model}.all(limit: per_page, offset: offset)
             response.json({ data: records.map(&:to_h), count: #{model}.count, page: page, per_page: per_page })
@@ -3061,17 +3026,40 @@ module Tina4
     DEFAULT_PORT = 7147
     DEFAULT_HOST = "0.0.0.0"
 
-    # Priority: CLI flag > ENV var > default
+    # Priority: CLI flag > TINA4_PORT > PORT (deprecated) > default.
+    #
+    # This used to read bare PORT only, ignoring TINA4_PORT entirely, while
+    # Tina4.resolve_bind_port (which WebServer/Tina4.run! use) and
+    # Tina4.mcp_port (the +2000 supervisor port) both already read
+    # TINA4_PORT first. So under `tina4ruby serve` with only TINA4_PORT set,
+    # this method alone fell through to bare PORT/DEFAULT_PORT while the
+    # AI port (base+1000, derived from THIS resolved base) and the supervisor
+    # port derived from a DIFFERENT base -- three ports, two answers for the
+    # same knob (DUALPORT-DEC-02, DUALPORT-BASE-PRECEDENCE). Not delegated to
+    # Tina4.resolve_bind_port itself: this runs before `require_relative
+    # "../tina4"` below, so the Tina4 module is not loaded yet at this point.
     def resolve_config(key, cli_value)
       case key
       when :port
         return cli_value if cli_value
+        tina4_port = ENV["TINA4_PORT"]
+        return tina4_port.to_i if tina4_port && tina4_port.match?(/\A\d+\z/)
         return ENV["PORT"].to_i if ENV["PORT"] && !ENV["PORT"].empty?
         DEFAULT_PORT
       when :host
         return cli_value if cli_value
+        # Host: CLI flag > TINA4_HOST > HOST > default. TINA4_HOST wins over the
+        # legacy plain HOST so a stray OS-level HOST (shared CI runners) can't
+        # silently override the framework's bind. Parity with Python's
+        # resolve_config.
+        return ENV["TINA4_HOST"] if ENV["TINA4_HOST"] && !ENV["TINA4_HOST"].empty?
         return ENV["HOST"] if ENV["HOST"] && !ENV["HOST"].empty?
-        DEFAULT_HOST
+        # DEVADMIN-DEC-02 (feature 127): in dev/serve mode the dashboard exposes
+        # an unauthenticated file/SQL/RCE surface, so the DEFAULT bind is
+        # loopback, not 0.0.0.0. Only the DEFAULT changes: production
+        # (TINA4_DEBUG off) keeps 0.0.0.0, and a developer who WANTS network
+        # exposure sets TINA4_HOST=0.0.0.0 to override deliberately.
+        Tina4.truthy?(ENV["TINA4_DEBUG"]) ? "127.0.0.1" : DEFAULT_HOST
       end
     end
 

data/lib/tina4/database.rb

@@ -745,7 +745,12 @@ module Tina4
       @pk_cache ||= {}
       unless @pk_cache.key?(table)
         @pk_cache[table] = begin
-          columns(table).select { |c| c[:primary_key] }.map { |c| c[:name].to_s }
+          pk_columns = columns(table).select { |c| c[:primary_key] }
+          # ADR-0044 amendment: sort by primary_key_position so a composite
+          # PRIMARY KEY (b, a) returns ["b", "a"] (declared key order), not
+          # table-column order. A column with no reported position sorts last.
+          pk_columns.sort_by! { |c| [c[:primary_key_position].nil? ? 1 : 0, c[:primary_key_position] || 0] }
+          pk_columns.map { |c| c[:name].to_s }
         rescue StandardError
           []
         end
@@ -958,37 +963,39 @@ module Tina4
     # and let the outer transaction commit them.
     def execute_many(sql, params_list = [])
       params_list ||= []
-      already_pinned = !Thread.current[@tx_pin_key].nil?
-      drv = current_driver
-      Thread.current[@tx_pin_key] = drv unless already_pinned
+      # ADR-0044 (DBA-B01): empty input is a successful no-op - it opens no
+      # transaction, calls no driver, and performs no write.
+      if params_list.empty?
+        return Tina4::DatabaseResult.new([], affected_rows: 0, last_id: nil, db: self)
+      end
 
+      # ADR-0044 (DBA-D02): the facade delegates to the driver's OWN
+      # execute_many exactly ONCE - it does not loop execute() itself. Native
+      # batching (one multi-row VALUES round-trip instead of one per row: 500
+      # rows measured 9848ms on PostgreSQL row-at-a-time against 15.8ms
+      # batched - 625x, MySQL 216x, MSSQL 121x) is the DRIVER's job.
+      #
+      # start_transaction/commit/rollback already correctly nest (depth
+      # counter) when called from inside an existing explicit transaction, so
+      # this brackets exactly the way a standalone start_transaction +
+      # execute + commit sequence would.
+      start_transaction
+      drv = current_driver # now returns the just-pinned driver
       begin
-        drv.begin_transaction unless already_pinned
-        begin
-          # ONE round-trip per CHUNK instead of one per ROW. Looping execute()
-          # here pays a full network round-trip for every row: 500 rows took
-          # 9848ms on PostgreSQL against 15.8ms as a single multi-row VALUES
-          # (625x), MySQL 216x, MSSQL 121x. build_batch_inserts returns an empty
-          # array for anything it cannot collapse safely - RETURNING, upserts,
-          # non-INSERT statements, ragged rows, Firebird - and the row-at-a-time
-          # loop then runs unchanged.
-          batched = SQLTranslator.build_batch_inserts(sql, params_list, get_database_type)
-          if batched.empty?
-            params_list.each { |params| drv.execute(sql, params) }
-          else
-            batched.each { |chunk_sql, chunk_params| drv.execute(chunk_sql, chunk_params) }
-          end
-          drv.commit unless already_pinned
-        rescue => e
-          drv.rollback unless already_pinned
-          @last_error = e.message
-          raise e
-        end
-      ensure
-        Thread.current[@tx_pin_key] = nil unless already_pinned
+        raw = drv.execute_many(sql, params_list)
+        commit
+      rescue => e
+        rollback
+        @last_error = e.message
+        raise e
       end
 
-      last_id = begin
+      # Normalise whatever the driver returned (a Hash {affected_rows:,
+      # last_id:} today) into the shared aggregate result. affected_rows is
+      # the total ROW count - chunking/native batching must stay invisible.
+      affected = raw.is_a?(Hash) ? raw[:affected_rows] : params_list.length
+      last_id = raw.is_a?(Hash) ? raw[:last_id] : nil
+      last_id ||= begin
         drv.last_insert_id
       rescue StandardError
         nil
@@ -1001,7 +1008,7 @@ module Tina4
       # double-apply.
       Tina4::DatabaseResult.new(
         [],
-        affected_rows: params_list.length,
+        affected_rows: affected,
         last_id: last_id,
         db: self
       )
@@ -1177,6 +1184,15 @@ module Tina4
     def get_next_id(table, pk_column: "id", generator_name: nil)
       drv = current_driver
 
+      # MongoDB — a DEDICATED atomic counter (findOneAndUpdate($inc) keyed by
+      # _id), monotonic and concurrency-safe. NEVER routed through the relational
+      # tina4_sequences path, whose arithmetic '+ 1' UPDATE has no MongoDB
+      # translation (the increment would be silently dropped and every call
+      # return the same id — a duplicate-key generator).
+      if @driver_name == "mongodb"
+        return drv.get_next_id(table, pk_column)
+      end
+
       # Firebird — use generators
       if @driver_name == "firebird"
         gen_name = generator_name || "GEN_#{table.upcase}_ID"
@@ -1197,27 +1213,41 @@ module Tina4
       # PostgreSQL — try sequence first, auto-create if missing
       if @driver_name == "postgres"
         seq_name = generator_name || "#{table.downcase}_#{pk_column.downcase}_seq"
+        # Fast path: the sequence already exists — nextval() is atomic.
         begin
           rows = drv.execute_query("SELECT nextval('#{seq_name}') AS next_id")
           row = rows.is_a?(Array) ? rows.first : nil
           val = row_value(row, :next_id) || row_value(row, :nextval)
           return val.to_i if val
         rescue
-          # Sequence does not exist — auto-create it seeded from MAX
-          begin
-            max_rows = drv.execute_query("SELECT COALESCE(MAX(#{pk_column}), 0) AS max_id FROM #{table}")
-            max_row = max_rows.is_a?(Array) ? max_rows.first : nil
-            max_val = row_value(max_row, :max_id)
-            start_val = max_val ? max_val.to_i + 1 : 1
-            drv.execute("CREATE SEQUENCE #{seq_name} START WITH #{start_val}")
-            drv.commit rescue nil
-            rows = drv.execute_query("SELECT nextval('#{seq_name}') AS next_id")
-            row = rows.is_a?(Array) ? rows.first : nil
-            val = row_value(row, :next_id) || row_value(row, :nextval)
-            return val&.to_i || start_val
-          rescue
-            # Fall through to sequence table fallback
-          end
+          # Sequence missing — create it idempotently below.
+        end
+
+        # First use: create the sequence IDEMPOTENTLY (CREATE SEQUENCE IF NOT
+        # EXISTS), seeded from MAX(pk). Two concurrent first-callers therefore
+        # share ONE counter — the loser's create is a no-op, not an error, so it
+        # never falls to the tina4_sequences table and draws a DUPLICATE id from
+        # a second, independent counter (the first-use race).
+        begin
+          max_rows = drv.execute_query("SELECT COALESCE(MAX(#{pk_column}), 0) AS max_id FROM #{table}")
+          max_row = max_rows.is_a?(Array) ? max_rows.first : nil
+          max_val = row_value(max_row, :max_id)
+          start_val = max_val ? max_val.to_i + 1 : 1
+          drv.execute("CREATE SEQUENCE IF NOT EXISTS #{seq_name} START WITH #{start_val}")
+          drv.commit rescue nil
+        rescue
+          # A concurrent creator won the catalog race — the sequence exists now.
+        end
+
+        # ALWAYS draw from the sequence now that it exists. Never fall to the
+        # sequence table just because our own CREATE lost the race.
+        begin
+          rows = drv.execute_query("SELECT nextval('#{seq_name}') AS next_id")
+          row = rows.is_a?(Array) ? rows.first : nil
+          val = row_value(row, :next_id) || row_value(row, :nextval)
+          return val.to_i if val
+        rescue
+          # Truly cannot use a sequence — last-resort table below.
         end
       end
 
@@ -1293,9 +1323,14 @@ module Tina4
     # error is captured on @last_error and re-raised. Returns the first row (a
     # Hash) or nil on a SUCCESSFUL "no row" read.
     def fetch_one_direct(sql, params)
-      result = fetch(sql, params, limit: 1, no_cache: true)
+      # ADR-0044 (DBA-D03): delegates to the adapter's OWN fetch_one exactly
+      # once - no pagination count probe (the old path ran the full paginated
+      # #fetch, which the driver builds via a COUNT(*) subquery + LIMIT/OFFSET
+      # SQL, just to keep the first row).
+      drv = current_driver
+      result = drv.fetch_one(sql, params)
       @last_error = nil
-      result.first
+      result
     rescue => e
       @last_error = driver_error_message(current_driver, e)
       raise
@@ -1498,9 +1533,16 @@ module Tina4
         # Row likely already exists (PK conflict) — fine, keep going.
         drv.rollback rescue nil
       end
-      drv.execute("UPDATE tina4_sequences SET current_value = current_value + 1 WHERE seq_name = ?", [seq_name])
+      # Single ATOMIC increment-and-return. The old path did the UPDATE then a
+      # SEPARATE SELECT: between them another caller could increment and commit,
+      # so both read the same value and returned a DUPLICATE id (a TOCTOU).
+      # PostgreSQL (the engine that reaches this fallback) supports
+      # UPDATE ... RETURNING, so the value read is exactly the one just written.
+      rows = drv.execute_query(
+        "UPDATE tina4_sequences SET current_value = current_value + 1 WHERE seq_name = ? RETURNING current_value",
+        [seq_name]
+      )
       drv.commit rescue nil
-      rows = drv.execute_query("SELECT current_value FROM tina4_sequences WHERE seq_name = ?", [seq_name])
       row = rows.is_a?(Array) ? rows.first : nil
       val = row_value(row, :current_value)
       raise "get_next_id: sequence row '#{seq_name}' missing" if val.nil?
@@ -1765,7 +1807,13 @@ module Tina4
       klass_name = DRIVERS[@driver_name]
       raise "Unknown database driver: #{@driver_name}" unless klass_name
       klass = Object.const_get(klass_name)
-      klass.new
+      driver = klass.new
+      # ADR-0044 / DBA-S02: fail loud, at registration, when the driver does
+      # not implement every required adapter capability - instead of failing
+      # later with a bare NoMethodError on whichever call path touches the
+      # gap first.
+      Tina4::DatabaseAdapter.validate!(driver, @driver_name)
+      driver
     rescue NameError
       raise "Driver #{klass_name} not loaded. Install the required gem."
     end

data/lib/tina4/database_adapter.rb

@@ -39,27 +39,48 @@ module Tina4
   # distinction is the whole point: including this module makes every driver
   # respond to everything, so +respond_to?+ stopped being able to tell the
   # difference.
+  # ADR-0044 / DBA-S02: a registered adapter does not satisfy the Tina4
+  # database adapter contract. Raised at registration time, naming the
+  # adapter and the missing capability.
+  class AdapterContractError < StandardError; end
+
+  # ADR-0044 / DBA-P02: a provider/deployment cannot guarantee an atomic
+  # multi-row batch. Raised by the shared execute_many default (or a driver's
+  # own override) before any row is written.
+  class UnsupportedAtomicBatchError < StandardError; end
+
+  # ADR-0044 / DBA-B05: a ragged/mismatched parameter set in a batch. Raised
+  # before any row of the batch is written.
+  class BindingCountMismatchError < StandardError; end
+
   module DatabaseAdapter
-    # Methods a driver MUST override. Kept as data so the conformance spec can
-    # read it instead of maintaining a second copy of the list.
-    # The REDESIGNED contract: only what genuinely differs per engine.
+    # The exact fourteen capabilities every driver must provide (ADR-0044,
+    # plan/v3/fixtures/adapter_contract.json). None is optional. Kept as data
+    # so the conformance spec can read it instead of maintaining a second copy.
     #
-    # CRUD (insert/update/delete), executeMany, fetchOne and DDL
-    # (create_table/add_column) are NOT here. They are composable above the
-    # adapter from execute + fetch + get_database_type, and Ruby was already
-    # doing exactly that in the facade - which is why Ruby's driver layer is
-    # 1335 LOC against PHP's 5823 for the same job. The first contract this row
-    # produced would have made Ruby write those seven more times; this one keeps
-    # the shape Ruby already had and asks the other three to adopt it.
+    # CRUD (insert/update/delete) and DDL (create_table/add_column) are NOT
+    # here - they are composable above the adapter from execute +
+    # get_database_type, and Ruby was already doing exactly that in the
+    # facade, which is why Ruby's driver layer is 1335 LOC against PHP's 5823
+    # for the same job. executeMany and fetchOne, by contrast, ARE required
+    # adapter primitives under ADR-0044 (superseding the original redesign
+    # that placed them above the adapter) - see execute_many/fetch_one below.
     CONTRACT = %i[
-      open close get_database_type
-      execute fetch
+      connect close get_database_type
+      execute execute_many fetch fetch_one
       start_transaction commit rollback autocommit
-      get_tables get_columns table_exists
-      last_insert_id error
+      tables columns table_exists?
     ].freeze
 
-    CONTRACT.each do |name|
+    # The subset with NO usable generic default - a driver MUST override
+    # these or the raising stub is inherited verbatim.
+    ABSTRACT_CONTRACT = %i[
+      connect close get_database_type
+      execute commit rollback
+      tables columns
+    ].freeze
+
+    ABSTRACT_CONTRACT.each do |name|
       define_method(name) do |*_args, **_kwargs, &_block|
         raise NotImplementedError,
               "#{self.class} does not implement ##{name}, which the Tina4 " \
@@ -67,6 +88,139 @@ module Tina4
       end
     end
 
+    # `open` is the pre-3.14 spelling every Ruby driver's constructor already
+    # calls; `connect` is the ADR-0044 canonical lifecycle name. A temporary
+    # forwarding alias, to be removed or explicitly deprecated before 3.14.
+    def open(*args, **kwargs)
+      connect(*args, **kwargs)
+    end
+
+    # `begin_transaction` is every existing driver's real spelling;
+    # `start_transaction` is the ADR-0044 canonical name (matches Python/PHP/
+    # Node). A thin forwarding default, exactly like `open` above.
+    def start_transaction(*args, **kwargs)
+      begin_transaction(*args, **kwargs)
+    end
+
+    # -- Capabilities with a REAL, usable generic default -------------------
+    # Every driver already implements execute_query/tables (required above)
+    # with identical spelling, so these compose safely for any driver that
+    # does not provide its own optimized override.
+
+    # ADR-0044: the adapter-level read-many primitive. Returns a native list
+    # of records with NO pagination envelope and NO count probe - the
+    # facade (Database#fetch) owns pagination and the true-total count.
+    def fetch(sql, params = [])
+      execute_query(sql, params)
+    end
+
+    # ADR-0044: one native record or nil. No pagination count probe.
+    def fetch_one(sql, params = [])
+      fetch(sql, params).first
+    end
+
+    # ADR-0044: table_exists? is required on the adapter. Drivers that expose
+    # a native, efficient check (SQLite, MySQL, MSSQL) override this; the rest
+    # get a correct, if less efficient, default from the required `tables`.
+    def table_exists?(name)
+      tables.any? { |t| t.to_s.downcase == name.to_s.downcase }
+    end
+
+    # ADR-0044: readable and writable native boolean, defaulting true.
+    def autocommit
+      @tina4_autocommit.nil? ? true : @tina4_autocommit
+    end
+
+    def autocommit=(value)
+      @tina4_autocommit = value
+    end
+
+    # ADR-0044 / DBA-P02: whether this adapter's deployment can guarantee an
+    # atomic multi-row batch write. Every built-in driver defaults to true; a
+    # deployment that genuinely cannot (a standalone MongoDB without a
+    # replica set is the motivating real case) sets this false so
+    # execute_many rejects BEFORE the first write.
+    def supports_atomic_batch
+      @tina4_supports_atomic_batch.nil? ? true : @tina4_supports_atomic_batch
+    end
+
+    def supports_atomic_batch=(value)
+      @tina4_supports_atomic_batch = value
+    end
+
+    # ADR-0044: one aggregate result for the whole batch - {affected_rows:,
+    # last_id:}. Transaction OWNERSHIP is deliberately NOT here: the facade
+    # (Database#execute_many) brackets begin/commit/rollback around exactly
+    # one call to this method, exactly as it already does for a standalone
+    # start_transaction()/execute()/commit() sequence, so a driver that
+    # overrides this for native batching never has to duplicate that policy.
+    def execute_many(sql, params_list = [])
+      rows = params_list || []
+      return { affected_rows: 0, last_id: nil } if rows.empty?
+
+      # ADR-0044 (DBA-B05): a ragged parameter set must fail BEFORE any
+      # durable partial success. Checked generically (every row's length must
+      # match the first) rather than parsing the SQL's own placeholder count,
+      # so it holds for every driver without a dialect-specific parser.
+      expected = rows.first.length
+      rows.each do |params|
+        next if params.length == expected
+
+        raise Tina4::BindingCountMismatchError,
+              "execute_many binding count mismatch - expected #{expected} " \
+              "parameters, got #{params.length}"
+      end
+
+      if !supports_atomic_batch && rows.length > 1
+        raise Tina4::UnsupportedAtomicBatchError,
+              "provider #{get_database_type.inspect} cannot guarantee an atomic " \
+              "batch write on this deployment (required deployment capability: " \
+              "a transaction-capable configuration) - rejected before the first " \
+              "write rather than risking partial durability"
+      end
+
+      # ONE round-trip per CHUNK instead of one per ROW - see
+      # Tina4::SQLTranslator.build_batch_inserts for the measured 121x-625x.
+      batched = Tina4::SQLTranslator.build_batch_inserts(sql, rows, get_database_type)
+      if batched.empty?
+        rows.each { |params| execute(sql, params) }
+      else
+        batched.each { |chunk_sql, chunk_params| execute(chunk_sql, chunk_params) }
+      end
+
+      last_id = begin
+        last_insert_id
+      rescue StandardError
+        nil
+      end
+      { affected_rows: rows.length, last_id: last_id }
+    end
+
+    # Fail loud when a class does not declare every required capability.
+    #
+    # For ABSTRACT_CONTRACT this checks the method was actually OVERRIDDEN
+    # (implemented_by?, below) rather than merely inherited as the raising
+    # stub. For the capabilities with a real generic default (execute_many,
+    # fetch, fetch_one, table_exists?, autocommit, supports_atomic_batch),
+    # simple presence is sufficient - the module's own default IS a complete,
+    # correct implementation.
+    def self.validate!(adapter_object, name = nil)
+      label = name || adapter_object.class.name
+      missing = CONTRACT.select do |capability|
+        if ABSTRACT_CONTRACT.include?(capability)
+          !implemented_by?(adapter_object, capability)
+        else
+          !adapter_object.respond_to?(capability)
+        end
+      end
+      return if missing.empty?
+
+      raise Tina4::AdapterContractError,
+            "adapter #{label.inspect} does not implement the required Tina4 " \
+            "database adapter contract capabilities: #{missing.join(', ')} " \
+            "(ADR-0044 / plan/v3/fixtures/adapter_contract.json)"
+    end
+
     # == Bounding the connect
     #
     # A connect that can block forever hangs the whole application with NO log,