tina4ruby 3.11.19 → 3.11.35

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 913dfbf6820b99da3ff8f0b5a845fb23239736ccc1db30eb958d664fba6abe9f
-  data.tar.gz: c7c39ce01253b8dc60edc30550b004914ac9c4742ee2efabfdedab44dfe984f7
+  metadata.gz: 7dfb1cf2a3f34468c680f80f120b935a59348b7bab428fa5ba8c738a2a9ddf85
+  data.tar.gz: 7ceb6e23bc01350d5de21c77fd4d7902a2a314933a5290a6db3dac272060865a
 SHA512:
-  metadata.gz: c926a2b39b248a45112e3f323174049ccdb0955c07ce3491a9346c837776cca37707ce54ecca21320ad71599b8d537a78eedadf4e675cd8c2b71dcfa6415ca39
-  data.tar.gz: caf6b606d28154e7ed8ded6e2519cc4a45f10a9034644f15f82625eace4e2747dbc27d845dadf0f0881a1c180c38a465428976a7be6d7b1c52b4239f637fd793
+  metadata.gz: f27c8ed10bc2c080ed765060989dafdc1c05c04bb255ac7a093cda62b692965e940b81d46f9b8f170ef0e3afd9cee44ee63d82eadc09410c34ef29338f1192ec
+  data.tar.gz: 694ef83820ce2021da6ae51013259590fd70374ac2170831d039af3cb9dfa3a30ab1bf7ff691c4c8bcdaadefdf7e5ca9901c30a8a537b69ade99c8aaa8cb1c12

data/lib/tina4/dev_admin.rb

@@ -5,8 +5,6 @@ require "digest"
 require "tmpdir"
 require "net/http"
 require "uri"
-require "fileutils"
-require "shellwords"
 require_relative "metrics"
 
 module Tina4
@@ -316,55 +314,9 @@ module Tina4
         Tina4::Env.is_truthy(ENV["TINA4_DEBUG"])
       end
 
-      # Write `.tina4/mcp.json` so MCP-aware tools (Claude Code, Cursor) can
-      # auto-discover this project's live docs server. Idempotent — no-op if
-      # the file already matches the desired contents. Also appends `.tina4/`
-      # to the project's `.gitignore` if a git repo is present.
-      def auto_discover_mcp!(project_root: Dir.pwd)
-        return if @_mcp_auto_discovered
-        @_mcp_auto_discovered = true
-        return unless enabled?
-
-        port = ENV["TINA4_PORT"] || ENV["PORT"] || "7147"
-        url  = "http://localhost:#{port}/__dev/api/mcp"
-        target_dir = File.join(project_root, ".tina4")
-        target = File.join(target_dir, "mcp.json")
-        payload = {
-          "mcpServers" => {
-            "tina4-live-docs" => {
-              "url" => url,
-              "description" => "Live API docs for this Tina4 project (framework + user code)",
-            },
-          },
-        }
-        begin
-          FileUtils.mkdir_p(target_dir)
-          existing = if File.file?(target)
-                       (JSON.parse(File.read(target)) rescue {})
-                     else
-                       {}
-                     end
-          if existing != payload
-            File.write(target, JSON.pretty_generate(payload))
-          end
-
-          gitignore = File.join(project_root, ".gitignore")
-          if File.directory?(File.join(project_root, ".git"))
-            current = File.file?(gitignore) ? File.read(gitignore) : ""
-            unless current.lines.map(&:strip).include?(".tina4/") || current.lines.map(&:strip).include?(".tina4")
-              prefix = (!current.empty? && !current.end_with?("\n")) ? "\n" : ""
-              File.write(gitignore, "#{current}#{prefix}.tina4/\n")
-            end
-          end
-        rescue StandardError => e
-          Tina4::Log.warning("auto_discover_mcp! failed: #{e.message}") if defined?(Tina4::Log)
-        end
-      end
-
       # Handle a /__dev request; returns [status, headers, body] or nil if not a dev path
       def handle_request(env)
         return nil unless enabled?
-        auto_discover_mcp!
 
         path = env["PATH_INFO"] || "/"
         method = env["REQUEST_METHOD"]
@@ -453,9 +405,7 @@ module Tina4
           resolved = id ? error_tracker.resolve(id) : false
           json_response({ resolved: resolved, id: id })
         when ["POST", "/__dev/api/broken/clear"]
-          # "Clear All" button — flush every tracked error, not only the
-          # ones individually marked resolved. Matches PHP/Python.
-          error_tracker.clear_all
+          error_tracker.clear_resolved
           json_response({ cleared: true })
         when ["GET", "/__dev/api/websockets"]
           json_response({ connections: [], count: 0 })
@@ -544,66 +494,6 @@ module Tina4
         when ["GET", "/__dev/api/metrics/file"]
           file_path = (query_param(env, "path") || "").to_s
           json_response(Tina4::Metrics.file_detail(file_path))
-        when ["GET", "/__dev/api/thoughts"]
-          json_response(thoughts_payload)
-        when ["POST", "/__dev/api/supervise/create"]
-          body = read_json_body(env) || {}
-          json_response(proxy_supervisor("/supervise/create", method: "POST", body: body))
-        when ["GET", "/__dev/api/supervise/sessions"]
-          json_response(proxy_supervisor("/supervise/sessions", method: "GET", query: env["QUERY_STRING"]))
-        when ["GET", "/__dev/api/supervise/diff"]
-          json_response(proxy_supervisor("/supervise/diff", method: "GET", query: env["QUERY_STRING"]))
-        when ["POST", "/__dev/api/supervise/commit"]
-          body = read_json_body(env) || {}
-          json_response(proxy_supervisor("/supervise/commit", method: "POST", body: body))
-        when ["POST", "/__dev/api/supervise/cancel"]
-          body = read_json_body(env) || {}
-          json_response(proxy_supervisor("/supervise/cancel", method: "POST", body: body))
-        when ["POST", "/__dev/api/execute"]
-          body = read_json_body(env) || {}
-          execute_proxy(body)
-        when ["GET", "/__dev/api/files"]
-          json_response(files_list(env))
-        when ["GET", "/__dev/api/file"]
-          json_response(file_read_payload(query_param(env, "path")))
-        when ["GET", "/__dev/api/file/raw"]
-          file_raw_response(query_param(env, "path"))
-        when ["POST", "/__dev/api/file/save"]
-          body = read_json_body(env) || {}
-          json_response(file_save(body))
-        when ["POST", "/__dev/api/file/rename"]
-          body = read_json_body(env) || {}
-          json_response(file_rename(body))
-        when ["POST", "/__dev/api/file/delete"]
-          body = read_json_body(env) || {}
-          json_response(file_delete(body))
-        when ["GET", "/__dev/api/deps/search"]
-          json_response(deps_search(query_param(env, "q") || query_param(env, "query") || ""))
-        when ["POST", "/__dev/api/deps/install"]
-          body = read_json_body(env) || {}
-          json_response(deps_install(body))
-        when ["GET", "/__dev/api/git/status"]
-          json_response(git_status_payload)
-        when ["GET", "/__dev/api/mcp/tools"]
-          json_response(mcp_tools_list)
-        when ["POST", "/__dev/api/mcp/call"]
-          body = read_json_body(env) || {}
-          json_response(mcp_tool_call(body))
-        when ["GET", "/__dev/api/scaffold"]
-          json_response(scaffold_templates)
-        when ["POST", "/__dev/api/scaffold/run"]
-          body = read_json_body(env) || {}
-          json_response(scaffold_run(body))
-        when ["GET", "/__dev/api/docs/search"]
-          json_response(docs_search_payload(env))
-        when ["GET", "/__dev/api/docs/class"]
-          json_response(docs_class_payload(query_param(env, "name")))
-        when ["GET", "/__dev/api/docs/method"]
-          json_response(docs_method_payload(query_param(env, "class"), query_param(env, "name")))
-        when ["GET", "/__dev/api/docs/index"]
-          json_response(docs_index_payload(query_param(env, "source")))
-        when ["GET", "/__dev/api/docs/.well-known.json"]
-          json_response(docs_well_known_payload)
         when ["GET", "/__dev/api/graphql/schema"]
           begin
             gql = Tina4::GraphQL.new
@@ -1040,358 +930,6 @@ module Tina4
 
         { deployed: name, files: copied }
       end
-
-      # ── New dev-admin surface area (parity with Python/PHP) ────
-
-      def supervisor_base
-        base = ENV["TINA4_SUPERVISOR_URL"].to_s.strip
-        return base unless base.empty?
-        port = (ENV["TINA4_PORT"] || ENV["PORT"] || "7147").to_i + 2000
-        "http://127.0.0.1:#{port}"
-      end
-
-      def thoughts_payload
-        base = supervisor_base
-        begin
-          uri = URI.parse("#{base}/thoughts")
-          req = Net::HTTP::Get.new(uri)
-          resp = Net::HTTP.start(uri.host, uri.port, open_timeout: 2, read_timeout: 5) { |h| h.request(req) }
-          return JSON.parse(resp.body) if resp.is_a?(Net::HTTPSuccess)
-          { thoughts: [], error: "Supervisor returned #{resp.code}" }
-        rescue StandardError => e
-          { thoughts: [], error: e.message }
-        end
-      end
-
-      def proxy_supervisor(path, method: "GET", body: nil, query: nil)
-        base = supervisor_base
-        url = "#{base}#{path}"
-        url += "?#{query}" if query && !query.empty?
-        begin
-          uri = URI.parse(url)
-          req = case method.upcase
-                when "POST"
-                  r = Net::HTTP::Post.new(uri)
-                  r["Content-Type"] = "application/json"
-                  r.body = JSON.generate(body || {})
-                  r
-                else
-                  Net::HTTP::Get.new(uri)
-                end
-          resp = Net::HTTP.start(uri.host, uri.port, open_timeout: 2, read_timeout: 30) { |h| h.request(req) }
-          begin
-            JSON.parse(resp.body)
-          rescue JSON::ParserError
-            { body: resp.body, status: resp.code.to_i }
-          end
-        rescue StandardError => e
-          { error: e.message, supervisor: base }
-        end
-      end
-
-      def execute_proxy(body)
-        # Proxy POST /execute to the supervisor at framework_port + 2000.
-        # Pass through the response stream as-is (SSE or JSON).
-        base = supervisor_base
-        begin
-          uri = URI.parse("#{base}/execute")
-          req = Net::HTTP::Post.new(uri)
-          req["Content-Type"] = "application/json"
-          req["Accept"] = "text/event-stream"
-          req.body = JSON.generate(body || {})
-          http = Net::HTTP.new(uri.host, uri.port)
-          http.open_timeout = 2
-          http.read_timeout = 300
-          resp = http.request(req)
-          ct = resp["content-type"] || "application/json; charset=utf-8"
-          [resp.code.to_i, { "content-type" => ct }, [resp.body.to_s]]
-        rescue StandardError => e
-          body_str = JSON.generate({ error: e.message, supervisor: base })
-          [502, { "content-type" => "application/json; charset=utf-8" }, [body_str]]
-        end
-      end
-
-      def safe_project_path(rel_path)
-        root = File.expand_path(Dir.pwd)
-        resolved = File.expand_path(rel_path.to_s, root)
-        raise ArgumentError, "path escapes project directory" unless resolved.start_with?(root)
-        resolved
-      end
-
-      def files_list(env)
-        rel = query_param(env, "path") || "."
-        begin
-          target = safe_project_path(rel)
-          return { error: "Not found" } unless File.exist?(target)
-          return { error: "Not a directory" } unless File.directory?(target)
-          entries = Dir.children(target).sort.map do |name|
-            full = File.join(target, name)
-            {
-              name: name,
-              type: File.directory?(full) ? "dir" : "file",
-              size: File.file?(full) ? File.size(full) : 0
-            }
-          end
-          { path: rel, entries: entries, count: entries.size }
-        rescue => e
-          { error: e.message }
-        end
-      end
-
-      def file_read_payload(rel)
-        return { error: "path required" } if rel.nil? || rel.empty?
-        begin
-          target = safe_project_path(rel)
-          return { error: "Not found" } unless File.exist?(target)
-          return { error: "Not a file" } unless File.file?(target)
-          content = File.read(target, encoding: "utf-8", invalid: :replace, undef: :replace)
-          { path: rel, content: content, bytes: File.size(target) }
-        rescue => e
-          { error: e.message }
-        end
-      end
-
-      def file_raw_response(rel)
-        return json_response({ error: "path required" }) if rel.nil? || rel.empty?
-        begin
-          target = safe_project_path(rel)
-          return json_response({ error: "Not found" }) unless File.file?(target)
-          content = File.binread(target)
-          ct = case File.extname(target).downcase
-               when ".css" then "text/css"
-               when ".js"  then "application/javascript"
-               when ".json" then "application/json"
-               when ".html", ".htm" then "text/html"
-               when ".png" then "image/png"
-               when ".jpg", ".jpeg" then "image/jpeg"
-               when ".gif" then "image/gif"
-               when ".svg" then "image/svg+xml"
-               else "text/plain; charset=utf-8"
-               end
-          [200, { "content-type" => ct }, [content]]
-        rescue => e
-          json_response({ error: e.message })
-        end
-      end
-
-      def file_save(body)
-        rel     = body["path"].to_s
-        content = body["content"].to_s
-        return { error: "path required" } if rel.empty?
-        begin
-          target = safe_project_path(rel)
-          existed = File.exist?(target)
-          FileUtils.mkdir_p(File.dirname(target))
-          File.write(target, content, encoding: "utf-8")
-          Tina4::Plan.record_action(existed ? "patched" : "created", rel) if defined?(Tina4::Plan)
-          { saved: rel, bytes: content.bytesize }
-        rescue => e
-          { error: e.message }
-        end
-      end
-
-      def file_rename(body)
-        from = body["from"].to_s
-        to   = body["to"].to_s
-        return { error: "from/to required" } if from.empty? || to.empty?
-        begin
-          src = safe_project_path(from)
-          dst = safe_project_path(to)
-          return { error: "Source not found" } unless File.exist?(src)
-          FileUtils.mkdir_p(File.dirname(dst))
-          File.rename(src, dst)
-          { renamed: { from: from, to: to } }
-        rescue => e
-          { error: e.message }
-        end
-      end
-
-      def file_delete(body)
-        rel = body["path"].to_s
-        return { error: "path required" } if rel.empty?
-        begin
-          target = safe_project_path(rel)
-          return { error: "Not found" } unless File.exist?(target)
-          if File.directory?(target)
-            FileUtils.rm_rf(target)
-          else
-            File.delete(target)
-          end
-          { deleted: rel }
-        rescue => e
-          { error: e.message }
-        end
-      end
-
-      def deps_search(query)
-        return { results: [], count: 0, error: "query required" } if query.to_s.strip.empty?
-        begin
-          uri = URI.parse("https://rubygems.org/api/v1/search.json?query=#{URI.encode_www_form_component(query)}")
-          http = Net::HTTP.new(uri.host, uri.port)
-          http.use_ssl = true
-          http.open_timeout = 5
-          http.read_timeout = 8
-          resp = http.request(Net::HTTP::Get.new(uri))
-          if resp.is_a?(Net::HTTPSuccess)
-            gems = JSON.parse(resp.body)
-            results = gems.first(20).map do |g|
-              { name: g["name"], version: g["version"], info: g["info"].to_s[0, 200] }
-            end
-            { results: results, count: results.size }
-          else
-            { results: [], count: 0, error: "rubygems returned #{resp.code}" }
-          end
-        rescue => e
-          { results: [], count: 0, error: e.message }
-        end
-      end
-
-      def deps_install(body)
-        name = body["name"].to_s.strip
-        return { ok: false, error: "name required" } if name.empty?
-        # Append to Gemfile if not present — do NOT actually bundle install.
-        gemfile = File.join(Dir.pwd, "Gemfile")
-        return { ok: false, error: "No Gemfile at project root" } unless File.exist?(gemfile)
-        content = File.read(gemfile)
-        if content.include?("gem \"#{name}\"") || content.include?("gem '#{name}'")
-          return { ok: true, gem: name, note: "already in Gemfile" }
-        end
-        File.open(gemfile, "a") { |f| f.write("\ngem \"#{name}\"\n") }
-        { ok: true, gem: name, note: "added to Gemfile; run `bundle install`" }
-      end
-
-      def git_status_payload
-        begin
-          inside = `cd #{Shellwords.escape(Dir.pwd)} && git rev-parse --is-inside-work-tree 2>/dev/null`.strip
-          return { error: "Not a git repository" } if inside != "true"
-          branch = `cd #{Shellwords.escape(Dir.pwd)} && git branch --show-current 2>/dev/null`.strip
-          status = `cd #{Shellwords.escape(Dir.pwd)} && git status --porcelain 2>/dev/null`.strip.split("\n").reject(&:empty?)
-          recent = `cd #{Shellwords.escape(Dir.pwd)} && git log --oneline -5 2>/dev/null`.strip.split("\n").reject(&:empty?)
-          { branch: branch, status: status, recent_commits: recent }
-        rescue => e
-          { error: "git unavailable: #{e.message}" }
-        end
-      end
-
-      def mcp_tools_list
-        return { tools: [], count: 0 } unless defined?(Tina4::McpServer)
-        server = Tina4._default_mcp_server
-        list = server.tools.values.map do |t|
-          { name: t["name"], description: t["description"], schema: t["inputSchema"] }
-        end
-        { tools: list, count: list.size }
-      end
-
-      def mcp_tool_call(body)
-        tool_name = body["name"].to_s
-        args      = body["arguments"] || {}
-        return { error: "tool name required" } if tool_name.empty?
-        return { error: "MCP not loaded" } unless defined?(Tina4::McpServer)
-        server = Tina4._default_mcp_server
-        payload = JSON.generate({
-          "jsonrpc" => "2.0",
-          "id"      => 1,
-          "method"  => "tools/call",
-          "params"  => { "name" => tool_name, "arguments" => args }
-        })
-        raw = server.handle_message(payload)
-        return {} if raw.nil? || raw.empty?
-        JSON.parse(raw)
-      end
-
-      def scaffold_templates
-        # Expose built-in scaffold targets for the dev-admin UI.
-        { templates: [
-          { id: "route",      label: "Route file",           target: "src/routes" },
-          { id: "model",      label: "ORM model",            target: "src/orm" },
-          { id: "migration",  label: "SQL migration",        target: "migrations" },
-          { id: "middleware", label: "Middleware class",     target: "src/app" }
-        ] }
-      end
-
-      def scaffold_run(body)
-        kind = body["kind"].to_s
-        name = body["name"].to_s.strip
-        return { ok: false, error: "kind + name required" } if kind.empty? || name.empty?
-        project = Dir.pwd
-        case kind
-        when "route"
-          target = File.join(project, "src", "routes", "#{name}.rb")
-          FileUtils.mkdir_p(File.dirname(target))
-          File.write(target, "# #{name} routes\nTina4::Router.get(\"/api/#{name}\") do |req, res|\n  res.call({ hello: \"#{name}\" })\nend\n") unless File.exist?(target)
-          { ok: true, created: target.sub("#{project}/", "") }
-        when "model"
-          target = File.join(project, "src", "orm", "#{name}.rb")
-          FileUtils.mkdir_p(File.dirname(target))
-          cls = name.to_s.split(/[_-]/).map(&:capitalize).join
-          File.write(target, "class #{cls} < Tina4::ORM\n  integer_field :id, primary_key: true, auto_increment: true\n  string_field :name\nend\n") unless File.exist?(target)
-          { ok: true, created: target.sub("#{project}/", "") }
-        when "migration"
-          ts = Time.now.strftime("%Y%m%d%H%M%S")
-          target = File.join(project, "migrations", "#{ts}_#{name}.sql")
-          FileUtils.mkdir_p(File.dirname(target))
-          File.write(target, "-- migration: #{name}\n")
-          { ok: true, created: target.sub("#{project}/", "") }
-        when "middleware"
-          target = File.join(project, "src", "app", "#{name}.rb")
-          FileUtils.mkdir_p(File.dirname(target))
-          cls = name.to_s.split(/[_-]/).map(&:capitalize).join
-          File.write(target, "class #{cls}\n  def self.before_check(req, res); [req, res]; end\nend\n") unless File.exist?(target)
-          { ok: true, created: target.sub("#{project}/", "") }
-        else
-          { ok: false, error: "unknown kind: #{kind}" }
-        end
-      end
-
-      # ── Live Docs (Live API RAG) ─────────────────────────────────
-
-      def docs_search_payload(env)
-        q = (query_param(env, "q") || "").to_s
-        k = (query_param(env, "k") || "5").to_i
-        source = (query_param(env, "source") || "all").to_s
-        include_private = %w[1 true yes].include?((query_param(env, "include_private") || "").to_s.downcase)
-        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        results = Tina4::Docs.cached(Dir.pwd).search(
-          q, k: k, source: source, include_private: include_private
-        )
-        took_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0).round(2)
-        { ok: true, query: q, results: results, took_ms: took_ms }
-      end
-
-      def docs_class_payload(name)
-        spec = Tina4::Docs.cached(Dir.pwd).class_spec(name.to_s)
-        return { ok: false, error: "class not found: #{name}" } if spec.nil?
-        { ok: true, class: spec }
-      end
-
-      def docs_method_payload(class_fqn, name)
-        spec = Tina4::Docs.cached(Dir.pwd).method_spec(class_fqn.to_s, name.to_s)
-        return { ok: false, error: "method not found: #{class_fqn}##{name}" } if spec.nil?
-        { ok: true, method: spec }
-      end
-
-      def docs_index_payload(source)
-        idx = Tina4::Docs.cached(Dir.pwd).index
-        idx = idx.select { |e| e[:source] == source } if source && %w[framework user vendor].include?(source.to_s)
-        { ok: true, count: idx.size, entries: idx }
-      end
-
-      def docs_well_known_payload
-        {
-          ok: true,
-          service: "tina4-live-docs",
-          version: Tina4::VERSION,
-          framework: "tina4-ruby",
-          endpoints: {
-            search: "/__dev/api/docs/search?q=<query>&k=<int>&source=<framework|user|all>&include_private=<bool>",
-            class:  "/__dev/api/docs/class?name=<fqn>",
-            method: "/__dev/api/docs/method?class=<fqn>&name=<method>",
-            index:  "/__dev/api/docs/index?source=<framework|user|all>",
-          },
-          mcp: { url: "/__dev/api/mcp", tools: %w[api_search api_class api_method] },
-          spec: "https://tina4.com — Live API RAG plan/v3/22-LIVE-API-RAG.md",
-        }
-      end
     end
   end
 end

data/lib/tina4/drivers/firebird_driver.rb

@@ -5,6 +5,20 @@ module Tina4
     class FirebirdDriver
       attr_reader :connection
 
+      # 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
+      # network rotation; without this the next prepare crashes the request.
+      DEAD_CONN_MARKERS = [
+        "error writing data to the connection",
+        "error reading data from the connection",
+        "connection shutdown",
+        "connection lost",
+        "network error",
+        "connection is not active",
+        "broken pipe"
+      ].freeze
+
       def connect(connection_string, username: nil, password: nil)
         require "fb"
         require "uri"
@@ -21,10 +35,13 @@ module Tina4
                      db_path || connection_string.sub(/^firebird:\/\//, "")
                    end
 
-        opts = { database: database }
-        opts[:username] = db_user if db_user
-        opts[:password] = db_pass if db_pass
-        @connection = Fb::Database.new(**opts).connect
+        # Cache for transparent reconnect — never logged, lives only in
+        # driver memory alongside the connection it owns.
+        @connect_opts = { database: database }
+        @connect_opts[:username] = db_user if db_user
+        @connect_opts[:password] = db_pass if db_pass
+
+        open_connection
       rescue LoadError
         raise "Firebird driver requires the 'fb' gem. Install it with: gem install fb"
       end
@@ -34,22 +51,35 @@ module Tina4
       end
 
       def execute_query(sql, params = [])
-        rows = if params.empty?
-                 @connection.query(:hash, sql)
-               else
-                 @connection.query(:hash, sql, *params)
-               end
+        rows = with_reconnect do
+          if params.empty?
+            @connection.query(:hash, sql)
+          else
+            @connection.query(:hash, sql, *params)
+          end
+        end
         rows.map { |row| decode_blobs(stringify_keys(row)) }
       end
 
       def execute(sql, params = [])
-        if params.empty?
-          @connection.execute(sql)
-        else
-          @connection.execute(sql, *params)
+        with_reconnect do
+          if params.empty?
+            @connection.execute(sql)
+          else
+            @connection.execute(sql, *params)
+          end
         end
       end
 
+      # Public so specs (and curious operators) can verify the matcher
+      # behaviour without poking private methods.
+      def self.dead_connection?(error_or_message)
+        msg = error_or_message.respond_to?(:message) ? error_or_message.message : error_or_message.to_s
+        return false if msg.nil? || msg.empty?
+        lower = msg.downcase
+        DEAD_CONN_MARKERS.any? { |m| lower.include?(m) }
+      end
+
       def last_insert_id
         nil
       end
@@ -103,6 +133,34 @@ module Tina4
 
       private
 
+      def open_connection
+        @connection = Fb::Database.new(**@connect_opts).connect
+      end
+
+      # Force-close a stale handle and reopen using cached opts. Idempotent —
+      # safe to call when the connection is already gone.
+      def reconnect!
+        begin
+          @connection&.close
+        rescue StandardError
+          # connection already gone — nothing to clean up
+        end
+        @connection = nil
+        @transaction = nil
+        open_connection
+      end
+
+      # Run a block; if it raises with a dead-connection signature, reconnect
+      # once and retry. Skipped inside an explicit transaction — atomicity
+      # beats resilience there; the caller handles rollback.
+      def with_reconnect
+        yield
+      rescue StandardError => e
+        raise unless self.class.dead_connection?(e) && @transaction.nil?
+        reconnect!
+        yield
+      end
+
       def stringify_keys(hash)
         hash.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
       end