mutineer 1.4.0 → 1.6.0

data/lib/mutineer/parser.rb

@@ -10,9 +10,9 @@ module Mutineer
 
   # Thin boundary around Prism.
   #
-  # Both methods return a Prism::ParseResult so all callers use result.value,
-  # result.source.source (raw bytes), and result.errors uniformly. No wrapping
-  # struct.
+  # The parse methods return a Prism::ParseResult so all callers use
+  # result.value, result.source.source (raw bytes), and result.errors
+  # uniformly. No wrapping struct.
   class Parser
     # Parses a file with Prism.
     #
@@ -32,5 +32,14 @@ module Mutineer
     def self.parse_string(source)
       Prism.parse(source)
     end
+
+    # The comments of source text, without building its syntax tree: a few
+    # times cheaper than {.parse_string} for a caller that needs only these.
+    #
+    # @param source [String] source text.
+    # @return [Array<Prism::Comment>] its comments, in source order.
+    def self.comments(source)
+      Prism.parse_comments(source)
+    end
   end
 end

data/lib/mutineer/project.rb

@@ -28,6 +28,31 @@ module Mutineer
     # Walks an AST, maintaining a namespace stack, emitting Subjects.
     # Nested inside Project to signal its private role.
     class SubjectVisitor < Prism::Visitor
+      # Calls whose block is the body of the class they build: receiver name => method.
+      CLASS_BUILDERS = { "Data" => :define, "Struct" => :new, "Class" => :new, "Module" => :new }.freeze
+
+      # A constant name, or a path of them; Ruby allows Unicode in both.
+      CONSTANT_PATH = /\A[[:upper:]][[:word:]]*(?:::[[:upper:]][[:word:]]*)*\z/
+
+      # A name that reads like a constant name but may not be one (#216). It is
+      # the singleton class name of a `class << self` opened inside a def or a
+      # block that does not build a class, or built on a written path or
+      # `#<anonymous>` (`#<Class:Foo::X>` from `class Foo::X` inside `class << self`);
+      # or the `X` of `module self::X` or `self::X = ...` in a def or a block. The segment carries that mark (see
+      # {#singleton_name}, {#with_namespace}, {#assigned_owner}), and `scope`, the
+      # def or block whose `self` the name is under, or a new object when unknown.
+      class WrittenName < String
+        # @return [Object] the def or block node whose `self` the name is under.
+        attr_reader :scope
+
+        # @param name [String] the name as built.
+        # @param scope [Object] the def or block node whose `self` the name is under.
+        def initialize(name, scope = Object.new)
+          super(name)
+          @scope = scope
+        end
+      end
+
       attr_reader :subjects
 
       # Builds a subject visitor.
@@ -40,22 +65,33 @@ module Mutineer
         @subjects = []
         @singleton_depth = 0
         @module_function_active = false # bareword `module_function` seen in this module body
-        @module_function_names = []     # [namespace, name] from `module_function :a` / `module_function def` (#98)
+        @module_function_names = []     # [module key, name] from `module_function :a` / `module_function def` (#98)
+        @subject_keys = []              # the module key of each subject, by index
+        @body = Object.new              # identifies the class/module body or builder block being visited
+        @block_owner = nil
+        @block_namespace = nil
+        @owner_unknown = false
+        @assigned = nil
+        @singleton_cref = nil # the singleton class name, in a builder block inside `class << self`
+        @namespace_unknown = false # the namespace is under a singleton class (#208) or a block's `self` (#229)
+        @anonymous_block = false   # inside a builder block not assigned to a constant
+        @self_unknown = false      # inside a def or a block that is not a builder, so `self` is not the namespace
+        @self_scope = nil          # the def or block whose `self` the code runs with
+        @singleton_uncertain = false # the open `class << self` was inside a def or a non-builder block
         super()
       end
 
       # Promote `module_function :name` / `module_function def name` subjects to
       # singleton after the full walk — the naming call may appear before or after
       # the def, so it can't be decided at visit_def_node time (#20). Only methods
-      # of the module that made the call are promoted (#98); namespaces compare
-      # joined, since `module A::B` and nested `module A; module B` differ as arrays.
+      # of the module that made the call are promoted (#98), matched by {#module_key}.
       #
       # @return [void]
       def promote_module_functions!
         return if @module_function_names.empty?
 
         named = @module_function_names.to_set
-        @subjects.each { |s| s.singleton = true if named.include?([s.namespace.join("::"), s.name]) }
+        @subjects.each_with_index { |s, i| s.singleton = true if named.include?([@subject_keys[i], s.name]) }
       end
 
       # Visits class nodes and tracks namespace nesting.
@@ -77,25 +113,81 @@ module Mutineer
       # Track `module_function` so its methods are recorded as singletons (#20) —
       # the called form is the singleton method on the module object. Bareword
       # `module_function` flips all SUBSEQUENT defs in this body; the argument
-      # forms (`:sym`, `def`) name methods promoted after the walk.
+      # forms (`:sym`, `def`) name methods promoted after the walk. A builder
+      # block's defs belong to the class it builds; one not assigned to a
+      # constant has no name, so its subjects are marked `owner_unknown`, and a
+      # `module_function :name` in it promotes nothing. Elsewhere it promotes the
+      # methods of the same module, matched by {#module_key}.
       #
       # @param node [Prism::CallNode] call node.
       # @return [void]
       def visit_call_node(node)
+        if %i[public private protected].include?(node.name) && node.receiver.nil? && node.arguments.nil?
+          @module_function_active = false # without arguments, Ruby goes back to instance methods
+        end
         if node.name == :module_function && node.receiver.nil?
           args = node.arguments&.arguments || []
           if args.empty?
             @module_function_active = true
-          else
-            namespace = @namespace_stack.join("::")
+          elsif !@anonymous_block
             args.each do |arg|
-              @module_function_names << [namespace, arg.value.to_sym] if arg.is_a?(Prism::SymbolNode)
-              @module_function_names << [namespace, arg.name] if arg.is_a?(Prism::DefNode)
+              @module_function_names << [module_key, arg.value.to_sym] if arg.is_a?(Prism::SymbolNode)
+              @module_function_names << [module_key, arg.name] if arg.is_a?(Prism::DefNode)
             end
           end
         end
+        return super unless builds_class?(node)
+
+        anonymous = !@assigned&.first.equal?(node)
+        with_block_owner(anonymous ? [nil, @namespace_stack, true] : @assigned.last, anonymous) do
+          @self_scope = node.block
+          super
+        end
+      end
+
+      # A block that does not build a class may run with any `self` (`class_eval`,
+      # `instance_eval`, a callback), so a `class << self` in it names a singleton
+      # class Mutineer cannot be sure of (#216). A lambda is treated the same.
+      #
+      # @param node [Prism::BlockNode, Prism::LambdaNode] block or lambda node.
+      # @return [void]
+      def visit_block_node(node)
+        return super if node.equal?(@self_scope) # a builder block
+
+        saved_self = [@self_unknown, @self_scope]
+        @self_unknown = true
+        @self_scope = node
         super
+        @self_unknown, @self_scope = saved_self
+      end
+      alias visit_lambda_node visit_block_node
+
+      # Names the class a builder block assigned to this constant builds (see {#builds_class?}).
+      #
+      # `=`, `||=` and `&&=` store the class, so each names it; `+=` stores what `+`
+      # returns, so its builder is left unnamed.
+      #
+      # @param node [Prism::ConstantWriteNode, Prism::ConstantPathWriteNode, Prism::ConstantOrWriteNode,
+      #   Prism::ConstantAndWriteNode, Prism::ConstantPathOrWriteNode, Prism::ConstantPathAndWriteNode]
+      #   constant assignment.
+      # @return [void]
+      def visit_constant_write_node(node)
+        call = assigned_value(node.value)
+        return super unless builds_class?(call)
+
+        saved = @assigned
+        @assigned = [call, assigned_owner(node)]
+        begin
+          super
+        ensure
+          @assigned = saved
+        end
       end
+      alias visit_constant_path_write_node visit_constant_write_node
+      alias visit_constant_or_write_node visit_constant_write_node
+      alias visit_constant_and_write_node visit_constant_write_node
+      alias visit_constant_path_or_write_node visit_constant_write_node
+      alias visit_constant_path_and_write_node visit_constant_write_node
 
       # Methods inside `class << self` are class methods of the enclosing
       # namespace, but their def nodes have no receiver — track the singleton
@@ -109,7 +201,12 @@ module Mutineer
         return unless node.expression.is_a?(Prism::SelfNode)
 
         @singleton_depth += 1
+        saved_active = @module_function_active
+        saved_uncertain = @singleton_uncertain
+        @singleton_uncertain ||= @self_unknown # `self` here may be another object (#216)
         super
+        @module_function_active = saved_active # a visibility call in here is not the module body's
+        @singleton_uncertain = saved_uncertain
         @singleton_depth -= 1
       end
 
@@ -120,40 +217,266 @@ module Mutineer
       def visit_def_node(node)
         @subjects << Subject.new(
           file: @file,
-          namespace: @namespace_stack.dup,
+          namespace: (@block_namespace || @namespace_stack).dup,
           lexical: @lexical_stack.dup,
+          block_owner: @block_owner,
+          owner_unknown: @owner_unknown,
           name: node.name,
           singleton: !node.receiver.nil? || @singleton_depth.positive? || @module_function_active,
           def_node: node
         )
+        @subject_keys << module_key
+        saved_active = @module_function_active
+        saved_self = [@self_unknown, @self_scope]
+        @self_unknown = true # `self` in a method body is the receiver it is called on
+        @self_scope = node
         super
+        @module_function_active = saved_active # a visibility call in a method body runs only when it is called
+        @self_unknown, @self_scope = saved_self
       end
 
       private
 
+      # The module a `module_function` call and a def are matched by: its joined
+      # namespace, so a module reopened later in the file matches (#216), and
+      # `module A::B` matches nested `module A; module B`. An unknown owner that an
+      # anonymous builder block owns, or whose name has no {WrittenName} segment
+      # and is not built only from constant names (see {#named_segment?}), may be
+      # shared by another module, so it is matched only within this body (#208).
+      # Otherwise a name with a {WrittenName}
+      # segment is matched by that segment's scope and text, so openings under one
+      # `self` match each other, but not those under another, whether the owner is
+      # known or not (#229).
+      #
+      # @return [String, Object]
+      def module_key
+        namespace = @block_namespace || @namespace_stack
+        written = written?(namespace)
+        return @body if @owner_unknown && (@anonymous_block || !written && !namespace.all? { |s| named_segment?(s) })
+        return namespace.join("::") unless written
+
+        namespace.map { |s| s.is_a?(WrittenName) ? "#{s.scope.object_id}:#{s}" : s }.join("::")
+      end
+
+      # True when any segment of the namespace is a {WrittenName}.
+      #
+      # @param namespace [Array<String>] namespace segments.
+      # @return [Boolean]
+      def written?(namespace)
+        namespace.any?(WrittenName)
+      end
+
+      # True when a namespace segment is a constant name, or a singleton class
+      # (`#<Class:App::M>`) of constant names. A written path or `#<anonymous>` is
+      # not, nor is a singleton class name built on one ({WrittenName}).
+      #
+      # @param segment [String] namespace segment.
+      # @return [Boolean]
+      def named_segment?(segment)
+        !segment.is_a?(WrittenName) && segment.gsub(/#<Class:|>/, "").match?(CONSTANT_PATH) &&
+          (segment.start_with?("#<Class:") || !segment.include?("::"))
+      end
+
       # Runs the block with `path` pushed as the current namespace. A
       # root-anchored path (`module ::X` / `class ::X`) names the top-level X,
       # not X nested in the enclosing scope, so the namespace restarts there.
       # Bareword `module_function` state does not cross a class or module
       # boundary: each body starts without it, and the outer state returns after.
+      # A class or module `X` opened inside `class << self`, even within a builder
+      # block there, is a constant of the singleton class, which has no constant
+      # path. It and everything nested in it is named under `#<Class:...>` with
+      # its owner unknown (#208), and its body defines instance methods again.
+      # A compact `Foo::X` or a top-level `::X` there is named as written, and
+      # its owner is unknown too: redefine reopens the lexical chain without the
+      # singleton class, so constants the body looks up through it would not resolve.
+      # A `self::X` in any block is under the block's `self`, not the namespace
+      # around the block (#229). In a builder block that is the built class, so
+      # it is named under the builder's constant; in any other block (`class_eval`,
+      # a callback) `self` may be any object, so it is named under the innermost
+      # enclosing builder's constant, or else the enclosing namespace. Either way
+      # the last segment is a {WrittenName}, and it and everything nested in it
+      # has its owner unknown. Redefine reopens the lexical chain (`module Outer;
+      # module X`), which never reaches the block's `self`; reopening X through
+      # its constant with `class_eval`, as for `self::X = ...` in a builder block,
+      # would drop X from `Module.nesting`, so constants its body looks up would not resolve.
       #
       # @param path [Prism::Node] the class/module constant path.
       # @yield the class or module body visit.
       # @return [void]
       def with_namespace(path)
-        saved_stack = @namespace_stack
-        saved_lexical = @lexical_stack
-        saved_active = @module_function_active
-        name = extract_constant_name(path)
-        root = root_anchored?(path)
-        @namespace_stack = root ? [name] : saved_stack + [name]
-        @lexical_stack = saved_lexical + [root ? "::#{name}" : name]
-        @module_function_active = false
+        preserving_scope do
+          name = extract_constant_name(path)
+          root = root_anchored?(path)
+          in_singleton = !@singleton_cref.nil? || @singleton_depth.positive?
+          self_in_block = !in_singleton && !root && self_rooted?(path) && (!@block_namespace.nil? || @self_unknown)
+          @namespace_stack =
+            if root then [name]
+            elsif in_singleton then path.is_a?(Prism::ConstantPathNode) ? [path.slice] : [singleton_name, name]
+            elsif self_in_block then (@block_namespace || @namespace_stack) + [WrittenName.new(name, @self_scope)]
+            else @namespace_stack + [name]
+            end
+          @lexical_stack += [root ? "::#{name}" : name]
+          @module_function_active = false
+          @block_owner = @block_namespace = nil
+          # redefine reopens the lexical chain, which does not pass through the block's `self`
+          @namespace_unknown = @owner_unknown = in_singleton || self_in_block || @namespace_unknown
+          @singleton_depth = 0
+          @singleton_cref = nil
+          @anonymous_block = @self_unknown = @singleton_uncertain = false
+          @body = Object.new
+          yield
+        end
+      end
+
+      # Visitor state a class/module body or builder block sets for what it contains.
+      SCOPE_STATE = %i[@namespace_stack @lexical_stack @module_function_active @block_owner @block_namespace
+                       @owner_unknown @singleton_depth @singleton_cref @namespace_unknown @anonymous_block @body
+                       @self_unknown @self_scope @singleton_uncertain].freeze
+
+      # Runs the block and then restores every {SCOPE_STATE} variable, so a
+      # nested body's state never leaks out of it.
+      #
+      # @yield the nested visit.
+      # @return [void]
+      def preserving_scope
+        saved = SCOPE_STATE.map { |name| instance_variable_get(name) }
         yield
       ensure
-        @namespace_stack = saved_stack
-        @lexical_stack = saved_lexical
-        @module_function_active = saved_active
+        SCOPE_STATE.zip(saved) { |name, value| instance_variable_set(name, value) }
+      end
+
+      # Resolves the constant an assignment writes the way Ruby does. `X` is in the
+      # current namespace, `::X` and a path at the top level start from Object, and
+      # `self::X` is under the current class (the built class inside a builder
+      # block). In a block that does not build a class, `self` may be any object,
+      # so `self::X` there has its owner unknown (#229). Any other path is
+      # looked up at run time, so its owner is unknown
+      # and the subject is named as written. Lexically inside `class << self`,
+      # even within a builder block there, the constant belongs to the singleton
+      # class, which has no constant path, so its owner is unknown too, as is
+      # `X` or `self::X` in a class or module opened there (#208). A `::X` there
+      # is named `X`, still unknown (see {#with_namespace}).
+      #
+      # @param node [Prism::Node] constant assignment.
+      # @return [Array(String, Array<String>, Boolean)] owner, namespace, unknown.
+      def assigned_owner(node)
+        if @singleton_cref || @singleton_depth.positive?
+          written = node.respond_to?(:target) ? node.target.slice : node.name.to_s
+          return [nil, written.start_with?("::") ? [written.delete_prefix("::")] : [singleton_name, written], true]
+        end
+        unless node.respond_to?(:target)
+          namespace = @namespace_stack + [node.name.to_s]
+          return @namespace_unknown ? [nil, namespace, true] : named_owner(namespace)
+        end
+
+        names = []
+        path = node.target
+        while path.is_a?(Prism::ConstantPathNode)
+          names.unshift(path.name.to_s)
+          path = path.parent
+        end
+        # see {#with_namespace}; in a builder block too, so a later `module self::X` there matches it
+        if path.is_a?(Prism::SelfNode) && (@self_unknown || @block_namespace)
+          names[0] = WrittenName.new(names[0], @self_scope)
+        end
+        if path.is_a?(Prism::SelfNode) && (@self_unknown || @namespace_unknown && !@anonymous_block)
+          return [nil, (@block_namespace || @namespace_stack) + names, true]
+        end
+
+        base =
+          case path
+          when nil then []
+          when Prism::SelfNode then @block_namespace || @namespace_stack unless @owner_unknown
+          when Prism::ConstantReadNode then [path.name.to_s] if @namespace_stack.empty?
+          end
+        return [nil, [node.target.slice], true] unless base
+
+        @namespace_unknown ? [nil, base + names, true] : named_owner(base + names)
+      end
+
+      # Names the singleton class that owns the constants written here: `class << self`
+      # opens that of the current class (the built class inside a builder block),
+      # and a builder block inside `class << self` keeps the enclosing one. A block
+      # not assigned to a constant builds a class with no name, written `#<anonymous>`.
+      # Each nested `class << self` opens the singleton class of the one around it.
+      # A name built on a written path or `#<anonymous>`, or opened where `self` may
+      # be another object (in a def or a non-builder block), is a {WrittenName} (see {#module_key}).
+      #
+      # @return [String] e.g. `#<Class:App>`, or `#<Class:#<Class:App>>` two deep.
+      def singleton_name
+        return @singleton_cref unless @singleton_depth.positive?
+
+        base = @anonymous_block ? @namespace_stack + ["#<anonymous>"] : @block_namespace || @namespace_stack
+        name = @singleton_depth.times.reduce(base.join("::")) { |inner, _| "#<Class:#{inner}>" }
+        named = !@singleton_uncertain && (@owner_unknown ? base.all? { |s| named_segment?(s) } : !written?(base))
+        named ? name : WrittenName.new(name)
+      end
+
+      # The owner for a resolved namespace, root-anchored so the redefine
+      # wrapper loads onto that constant from any nesting.
+      #
+      # @param namespace [Array<String>] resolved namespace.
+      # @return [Array(String, Array<String>, Boolean)]
+      def named_owner(namespace)
+        ["::#{namespace.join("::")}", namespace, false]
+      end
+
+      # The value an assignment stores: the last statement inside parentheses or a
+      # `begin` without `rescue`, which Ruby returns from them.
+      #
+      # @param node [Prism::Node] assigned expression.
+      # @return [Prism::Node, nil]
+      def assigned_value(node)
+        loop do
+          body =
+            case node
+            when Prism::ParenthesesNode then node.body
+            when Prism::BeginNode then node.statements unless node.rescue_clause
+            end
+          return node unless body
+
+          node = body.is_a?(Prism::StatementsNode) ? body.body.last : body
+        end
+      end
+
+      # True when the node is `Data.define`, `Struct.new`, `Class.new` or `Module.new` with a block.
+      #
+      # @param node [Prism::Node, nil] node.
+      # @return [Boolean]
+      def builds_class?(node)
+        node.is_a?(Prism::CallNode) && node.block.is_a?(Prism::BlockNode) &&
+          CLASS_BUILDERS[node.receiver&.slice&.delete_prefix("::")] == node.name
+      end
+
+      # Runs the block with the defs it visits owned by the class a builder block builds.
+      # The block body defines instance methods of that class, even inside `class << self`,
+      # but its constants still land where the enclosing `class << self` puts them.
+      #
+      # @param owner [Array(String, Array<String>, Boolean)] the owner as written, its namespace,
+      #   and whether that name is unknown.
+      # @param anonymous [Boolean] true when the block is not assigned to a constant.
+      # @yield the builder call visit.
+      # @return [void]
+      def with_block_owner(owner, anonymous)
+        preserving_scope do
+          @singleton_cref = singleton_name if @singleton_depth.positive?
+          @block_owner, @block_namespace, @owner_unknown = owner
+          @anonymous_block = anonymous
+          @self_unknown = @singleton_uncertain = false
+          @module_function_active = false
+          @singleton_depth = 0
+          @body = Object.new
+          yield
+        end
+      end
+
+      # True when a constant path starts with `self` (e.g. `self::X`).
+      #
+      # @param node [Prism::Node] constant path node.
+      # @return [Boolean]
+      def self_rooted?(node)
+        node = node.parent while node.is_a?(Prism::ConstantPathNode)
+        node.is_a?(Prism::SelfNode)
       end
 
       # True when a constant path starts with `::` (e.g. `::X` or `::A::B`).

data/lib/mutineer/rails_worker_db.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module Mutineer
   # Per-worker database isolation for the daemon path.
   #
@@ -14,7 +16,9 @@ module Mutineer
   # forks cannot clobber each other's transactional fixtures. {after_fork} runs
   # inside a freshly-forked child and points that child's connection at the
   # worker's database BEFORE any test loads; transactional fixtures then
-  # repopulate that isolated database per test.
+  # repopulate that isolated database per test. On a slot's first use the worker
+  # database starts as a copy of the base test database, so it holds what the
+  # booted parent wrote, as the in-process backend sees it.
   #
   # Scope: SQLite adapter only (per-worker file, hermetic). Postgres per-worker
   # DBs (`CREATE DATABASE <db>-<worker>`) are not implemented yet; a non-SQLite
@@ -65,7 +69,7 @@ module Mutineer
       unless adapter.start_with?("sqlite")
         raise NotImplementedError,
               "worker-DB isolation currently provisions SQLite only (got adapter #{adapter.inspect}); " \
-              "Postgres per-worker provisioning is not yet supported. Use a SQLite test DB, or drop --jobs."
+              "Postgres per-worker provisioning is not yet supported. Use a SQLite test DB with --daemon, or drop --daemon to run serially."
       end
 
       per_worker_config(hash, worker)
@@ -95,22 +99,92 @@ module Mutineer
 
     # Child-side (after fork): route this process's ActiveRecord at the worker's
     # own database and confirm it is reachable, so a routing failure reads as
-    # `error` (via the daemon's child rescue) rather than a false verdict. Loads
-    # the schema into the worker database when a schema path is given
-    # (idempotent: schema.rb runs with `force: true`), covering a fresh worker
-    # file.
+    # `error` (via the daemon's child rescue) rather than a false verdict.
+    #
+    # With `seed: true` (the slot's first use) the worker database first becomes
+    # a copy of the base test database, schema and rows, so rows the daemon
+    # parent wrote while it booted (initializers, `--require` files) are there,
+    # as they are for the in-process backend (#222). The schema is then loaded
+    # only when the copy differs from `schema.rb` ({schema_current?}: schema
+    # version or stored `schema_sha1`, as in a stale or empty base database):
+    # `schema.rb` runs with `force: true`, which drops the copied rows of the
+    # tables it defines.
     #
     # @param worker [Integer] the worker slot index.
     # @param schema_path [String, nil] absolute path to `db/schema.rb`, or nil to skip.
+    # @param seed [Boolean] copy the base database into the worker database first.
     # @return [void]
-    def self.after_fork(worker, schema_path = nil)
+    def self.after_fork(worker, schema_path = nil, seed: false)
       return unless available?
 
-      ActiveRecord::Base.establish_connection(worker_db_config(worker))
-      load_schema(schema_path) if schema_path
+      config = worker_db_config(worker)
+      base   = ActiveRecord::Base.connection.select_value("SELECT file FROM pragma_database_list WHERE name = 'main'") if seed
+      ActiveRecord::Base.establish_connection(config)
+      seed_from(base) if seed
+      load_schema(schema_path) if schema_path && !schema_current?(schema_path)
       verify_connection!
     end
 
+    # Copy the base test database file into the worker database this fork is
+    # now connected to, with the SQLite online backup API: one consistent
+    # snapshot of the committed data (WAL included) that replaces whatever the
+    # worker file held (an earlier run, or a copy a timeout interrupted). Both
+    # ends are files SQLite itself opened, so no path rules are re-derived here.
+    #
+    # @param base_file [String] the base database file, from `pragma_database_list`.
+    # @return [void]
+    def self.seed_from(base_file)
+      codes  = SQLite3::Constants::ErrorCode
+      source = SQLite3::Database.new(base_file, readonly: true)
+      source.busy_timeout = 5000
+      backup = SQLite3::Backup.new(ActiveRecord::Base.connection.raw_connection, "main", source, "main")
+      # Another worker's process can hold a lock on the base file for a moment;
+      # BUSY/LOCKED steps are retried for up to 5 seconds, then the copy fails
+      # with a message that names the database (scored `error`).
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5
+      until (status = backup.step(-1)) == codes::DONE
+        retry_ok = [codes::BUSY, codes::LOCKED].include?(status) && Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+        raise "copying #{base_file} into the worker database failed (SQLite code #{status})" unless retry_ok
+
+        sleep 0.01
+      end
+    ensure
+      backup&.finish
+      source&.close
+    end
+
+    # True when the current database already holds the schema that `schema.rb`
+    # declares: its newest `schema_migrations` row matches the declared version,
+    # and the `schema_sha1` Rails stores in `ar_internal_metadata` matches the
+    # file, which catches an edited schema with the same version. No stored
+    # checksum counts as out of date, as in Rails' own `schema_up_to_date?`.
+    #
+    # @param schema_path [String] absolute path to `db/schema.rb`.
+    # @return [Boolean]
+    def self.schema_current?(schema_path)
+      text    = File.read(schema_path)
+      version = schema_file_version(text)
+      conn = ActiveRecord::Base.connection
+      base       = ActiveRecord::Base
+      migrations = "#{base.table_name_prefix}#{base.schema_migrations_table_name}#{base.table_name_suffix}"
+      metadata   = "#{base.table_name_prefix}#{base.internal_metadata_table_name}#{base.table_name_suffix}"
+      return false unless version && conn.table_exists?(migrations)
+      return false unless conn.select_values("SELECT version FROM #{conn.quote_table_name(migrations)}").map(&:to_i).max == version
+      return false unless conn.table_exists?(metadata)
+
+      conn.select_value("SELECT value FROM #{conn.quote_table_name(metadata)} WHERE key = 'schema_sha1'") ==
+        Digest::SHA1.hexdigest(text)
+    end
+
+    # The version a `schema.rb` declares in `define(version: ...)`, or nil. Pure
+    # string parse (no AR) so it is unit-testable in the zero-dep suite.
+    #
+    # @param text [String] the `schema.rb` source.
+    # @return [Integer, nil]
+    def self.schema_file_version(text)
+      text[/define\(version:\s*([\d_]+)/, 1]&.delete("_")&.to_i
+    end
+
     # Load a Rails `schema.rb` into the current connection with output silenced
     # (fork child stdout is already File::NULL; this is belt-and-braces).
     #