factory_hoist 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 932a7db6380072b0f2f85f0ec490d40e3e064476cfd6fedbbdd7addd6d344ab1
+  data.tar.gz: 7e8d769103fec0947c603a59bacc628eef8df9a5299627e371144c33f90950a9
+SHA512:
+  metadata.gz: 6a8a0683faa318e861d01f8b8bda4f35483910712dad4f11e3ceec60de73a6bfa17ce58afadd5421e389f8f600fe2527bf18eb1345b119a26734a4eb7120e7d0
+  data.tar.gz: 6fda5d4647831af4cbe8781de691e24063c9e4b3ddb454102c8902557c2f38014c1c8b4b52bce380bf061e8833e6295499e274a79dfca6263122d69bc086f7d1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,125 @@
+# FactoryHoist
+
+FactoryHoist creates FactoryBot records once at an RSpec example-group boundary, then gives every example an isolated in-memory copy. ActiveRecord changes are isolated with savepoints and rolled back when the group exits.
+
+## Installation
+
+Add the gem to the test group:
+
+```ruby
+group :test do
+  gem "factory_hoist"
+end
+```
+
+## Usage
+
+`hoist` uses the declaration's name as the FactoryBot factory by default. A block returns attribute overrides and can refer to ancestor declarations.
+
+```ruby
+RSpec.describe Order do
+  hoist(:company)
+  hoist(:user) { {company: company} }
+
+  context "paid" do
+    hoist(:order) { {user: user, state: :paid} }
+
+    it "can update its isolated copy" do
+      order.update!(state: :cancelled)
+    end
+
+    it "preserves relationships" do
+      expect(order.user).to equal(user)
+    end
+  end
+end
+```
+
+Traits and an alternate factory name are supported:
+
+```ruby
+hoist(:admin, :user, :admin, active: true)
+```
+
+The direct APIs delegate to FactoryBot:
+
+```ruby
+FactoryHoist.build(:user)
+FactoryHoist.create(:user)
+FactoryHoist.build_list(:user, 3)
+FactoryHoist.create_list(:user, 3)
+```
+
+Simple callback-free builds are compiled to a Ruby file under the system temporary directory and bypass FactoryBot's evaluation pipeline. Traits, callbacks, required constructors, and unsupported definitions automatically fall back to FactoryBot. Run the fixed-condition benchmark with:
+
+```console
+$ bundle exec ruby bench/fast_build.rb
+```
+
+Bulk insertion is explicitly unsafe because it skips validations and callbacks:
+
+```ruby
+FactoryHoist.unsafe_bulk_insert(:user, 10_000)
+```
+
+It uses FactoryBot's `attributes_for` and ActiveRecord's `insert_all!`; it is intended for performance and seed data only.
+
+### Configuration
+
+```ruby
+FactoryHoist.configure do |config|
+  config.subxid_budget = 60
+  config.suite_seed = ENV.fetch("FACTORY_HOIST_SEED", 0).to_i
+  config.paranoid_mode = false
+end
+```
+
+`subxid_budget` rebuilds an owned outer transaction after that many examples. Rebuilding is deferred while an active `before(:context)` hook has written database state that FactoryHoist cannot rematerialize; move that setup into `hoist` if the budget must remain strict. Set it to `0` to disable rebuilding. `suite_seed` makes `FactoryHoist.random` deterministic for a declaration path and key, including Faker-backed Fast Build attributes. `paranoid_mode` checks hoisted ActiveRecord rows before and after every example and raises if they changed.
+
+### Advice and statistics
+
+```console
+$ bundle exec factory_hoist advise spec/
+```
+
+The command runs the selected RSpec suite, then reports repeated literal factory calls, runtime references, degradation, and the 20 most expensive materializations. Runtime counters remain available through `FactoryHoist.stats.to_h`.
+
+## Constraints
+
+- Minitest accepts the same DSL and safely creates once per test; cross-test hoisting is intentionally disabled because Minitest has no portable group lifecycle.
+- Declarations that use example-local helpers, instance variables, `initialize_with`, or `to_create` are created inside the example transaction instead of being shared.
+- `after_commit` does not fire inside the managed transaction.
+- Objects that `Marshal` cannot copy silently use example-local creation and increment the degradation counter.
+- DatabaseCleaner truncation is incompatible and emits a warning; use its transaction strategy.
+- System specs need a shared database connection. Multi-database applications are not supported.
+- Raw SQL and `update_all` are rolled back between examples, but can still create ordering effects inside one example.
+
+## Development
+
+Run `bundle install`, then `bundle exec rake`. The suite includes an in-memory SQLite integration test for transaction and savepoint behavior.
+
+With a local PostgreSQL server available, verify the subtransaction budget, PostgreSQL statistics, and bulk-insert failure recovery using a temporary table:
+
+```console
+$ DATABASE_URL=postgresql:///postgres bundle exec ruby script/verify_postgresql
+```
+
+Parallel workers can clone a disconnected PostgreSQL template under an advisory lock, or a SQLite database through SQLite's online backup API:
+
+```ruby
+FactoryHoist.clone_database(
+  source: "postgresql:///app_test_template",
+  target: "app_test_1",
+  adapter: :postgresql
+)
+```
+
+The design-to-implementation adversarial review is recorded in [docs/adversarial-audit.md](docs/adversarial-audit.md).
+
+## Contributing
+
+Bug reports and pull requests are welcome.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bench/fast_build.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "factory_hoist"
+
+class BenchFastBuildUser
+  attr_accessor :first_name, :last_name, :email, :age, :city, :active
+end
+
+FactoryBot.define do
+  factory :bench_fast_build_user do
+    first_name { "Ada" }
+    last_name { "Lovelace" }
+    email { "#{first_name.downcase}.#{last_name.downcase}@example.test" }
+    age { 36 }
+    city { "London" }
+    active { true }
+  end
+end
+
+iterations = Integer(ENV.fetch("N", 20_000))
+FactoryHoist.build(:bench_fast_build_user)
+
+measure = lambda do |&block|
+  3.times.map do
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    iterations.times(&block)
+    Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+  end.sort[1]
+end
+
+factory_bot = measure.call { FactoryBot.build(:bench_fast_build_user) }
+factory_hoist = measure.call { FactoryHoist.build(:bench_fast_build_user) }
+speedup = factory_bot / factory_hoist
+
+puts format("FactoryBot %.3fs / FactoryHoist %.3fs / %.2fx", factory_bot, factory_hoist, speedup)
+abort "Fast Build did not reach 5x" if speedup < 5

data/bench/phase0_synthetic.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "active_record"
+require "factory_hoist"
+
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
+ActiveRecord::Schema.verbose = false
+ActiveRecord::Schema.define do
+  create_table(:phase0_companies) { |table| table.string :name, null: false }
+  create_table(:phase0_orders) do |table|
+    table.references :company, null: false
+    table.string :state, null: false
+  end
+end
+
+class Phase0Company < ActiveRecord::Base
+end
+
+class Phase0Order < ActiveRecord::Base
+  belongs_to :company, class_name: "Phase0Company"
+end
+
+FactoryBot.define do
+  factory :phase0_company do
+    name { "Acme" }
+  end
+  factory :phase0_order do
+    association :company, factory: :phase0_company
+    state { "paid" }
+  end
+end
+
+examples = Integer(ENV.fetch("N", 200))
+connection = ActiveRecord::Base.connection
+measure = lambda do |&block|
+  inserts = 0
+  subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do |_name, _start, _finish, _id, payload|
+    inserts += 1 if payload[:sql].match?(/\AINSERT/i)
+  end
+  times = 3.times.map do
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    block.call
+    Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+  end
+  [times.sort[1], inserts / 3]
+ensure
+  ActiveSupport::Notifications.unsubscribe(subscriber) if subscriber
+end
+
+baseline = measure.call do
+  examples.times do
+    connection.transaction(requires_new: true) do
+      FactoryBot.create(:phase0_order)
+      raise ActiveRecord::Rollback
+    end
+  end
+end
+
+let_it_be = measure.call do
+  connection.transaction(requires_new: true) do
+    shared = FactoryBot.create(:phase0_order)
+    examples.times do
+      connection.transaction(requires_new: true) do
+        Marshal.load(Marshal.dump(shared))
+        raise ActiveRecord::Rollback
+      end
+    end
+    raise ActiveRecord::Rollback
+  end
+end
+
+factory_hoist = measure.call do
+  FactoryHoist.configuration.factory_adapter = nil
+  FactoryHoist.configuration.subxid_budget = examples + 1
+  definition = FactoryHoist::Definition.new(:order, :phase0_order, [], {}, nil, "phase0")
+  session = FactoryHoist::Runtime::Session.new
+  group = Object.new
+  session.enter(group, {order: definition})
+  examples.times do
+    example = Object.new
+    example.define_singleton_method(:run) do
+      session.fetch(self, :order, definition, {order: definition})
+    end
+    session.around_example(example)
+  end
+  session.leave(group)
+end
+
+reduction = 1 - factory_hoist[1].fdiv(baseline[1])
+report = <<~REPORT
+  # Synthetic Phase 0 report
+
+  | Path | Median | INSERTs |
+  |---|---:|---:|
+  | FactoryBot | #{format("%.4fs", baseline[0])} | #{baseline[1]} |
+  | let_it_be equivalent | #{format("%.4fs", let_it_be[0])} | #{let_it_be[1]} |
+  | factory_hoist | #{format("%.4fs", factory_hoist[0])} | #{factory_hoist[1]} |
+
+  Record reduction: #{format("%.1f%%", reduction * 100)}
+  Dynamic-argument rate: 0.0% (synthetic fixture)
+  Tree depth: 1; writing examples per file: #{examples}
+  Stop decision: undetermined without the target suite and its target time.
+REPORT
+
+puts report
+File.write(ENV["REPORT"], report) if ENV["REPORT"]
+raise "synthetic record reduction missed 60%" if reduction < 0.6

data/docs/adversarial-audit.md

@@ -0,0 +1,50 @@
+# Adversarial implementation audit
+
+Audited against `.idea/factory_hoist-design.md` on 2026-09-01.
+
+## Verified
+
+| Requirement | Evidence |
+|---|---|
+| RSpec declaration collection, selected-example reference analysis, dependency propagation, and LCA scheduling | Tests for unused, descendant-only, reverse-ordered dependencies, filtered single-example runs, and dynamic references |
+| Safe fallback for dynamic inputs and unsupported factories | RSpec `let`, instance variables, custom Marshal failures, `initialize_with`, and `to_create` all deopt locally |
+| Group/example savepoints, context-hook isolation, rollback, and configurable rebuild budget | SQLite tests cover hook ordering, group/example-local late connections, reset cleanup, partial failures, local rollback, and leaking-row checks after failing hooks |
+| PostgreSQL subxid budget | 61 writes, one rebuild, no added `Subtrans` reads; statistics, bulk recovery, and reset cleanup verified locally and in CI |
+| Lazy graph copy with relationship identity and per-example memoization | RSpec integration tests |
+| Deterministic node/key seed | BLAKE2b-based seed test; Faker random source is scoped when Faker is loaded |
+| PCG random source | Canonical PCG32 vector, arbitrary-size integers, numeric ranges, real Faker inputs, reset reproducibility, and thread-isolated Faker scopes |
+| Failure locality | Materialization errors include the declaration node and key |
+| FactoryBot build/create/list compatibility | Unit and ActiveRecord integration tests, including FactoryBot-compatible block yields |
+| Fast Build | Bounded per-process paths, generated-file backtraces, reload-safe constants, association/alias semantics, generated-name safety, evaluator-name collisions, and no retry after evaluator errors; benchmark above 8x |
+| Bulk Writer | ActiveRecord `insert_all!`, native type casting, row diagnosis, and PostgreSQL outer-transaction recovery after failure |
+| DatabaseCleaner warning and paranoid row checks | Unit and ActiveRecord tests, including named, anonymous, composite-key, and keyless models |
+| RSpec and Minitest correctness | Primary-entrypoint load-order test; RSpec sharing; Minitest deliberately deoptimizes to per-test creation |
+| Packaging and CLI | Gem build, unpacked executable, and CI/full-suite coverage on the declared minimum Ruby 3.2 |
+| Process-parallel database initialization | SQLite online backup covers WAL recovery and exclusive no-overwrite creation; PostgreSQL verifies active-source refusal, lock release, successful clone, and existing-target refusal |
+| Phase 0 harness | Reproducible synthetic three-way benchmark in `docs/phase0-synthetic.md` |
+
+## Not claimable from this repository
+
+These are empirical acceptance gates, not library code:
+
+- G1's 60% record reduction, the 50% duplication stop condition, and the 30% dynamic-argument stop condition require the target application's full test suite.
+- Comparison against mechanically applied `let_it_be` plus `build_stubbed`, representative single-file timings, RSS, and three-run suite medians require that same suite.
+- MySQL behavior cannot be verified because no MySQL server is available in this environment.
+
+## Contradictions in the design
+
+- G2/G4 require no migration and an unchanged suite, while §3.2 requires explicit `hoist` declarations and §4.1 requires mechanical replacement. Both cannot be true simultaneously.
+- `ActiveRecord::Base.instantiate` creates an object treated as persisted, which does not preserve FactoryBot `build` semantics for a row that does not exist. Fast Build uses `new` and real model instances instead.
+- Generic circular-FK `INSERT + UPDATE` is impossible when both foreign keys are immediately enforced and non-null. It requires nullable/deferred constraints or preallocated keys, none of which the API or design specifies.
+- FactoryBot and database sequences are external mutable state. Node-seeding them would change their public values or ID strategy, while §6.2 requires the ID strategy to remain unchanged. The implementation node-seeds its PCG/Faker source only.
+
+## Deliberate safe degradation
+
+- Minitest cross-test sharing is disabled because the design leaves its portable group tree/lifecycle unresolved. The compatibility path remains correct and reports deoptimization.
+- Static reference analysis uses MRI bytecode. Dynamic, indirect, and non-MRI block declarations take the correct local fallback.
+- Fast Build keeps lazy attribute readers and a compatibility-only `method_missing` for model and FactoryBot helper methods instead of rewriting arbitrary Ruby blocks. Unsupported definitions fall back, while the 5x DoD remains enforced by the benchmark.
+- Phase 4 attribute-level read tracking has no defined output after A1 rejects it for correctness decisions. The advisor instead reports declaration references, unused hoists, degradation, and materialization cost.
+
+## Verdict
+
+The repository is implementation-complete for the coherent, testable subset and exposes runnable checks for SQLite, PostgreSQL, database cloning, Phase 0, and Fast Build. The design as written cannot be completely satisfied because of the contradictions above. Product-level completion also remains blocked on the mandatory target-suite measurements; claiming G1/G2 or the project stop/go decision without that input would be false.

data/docs/phase0-synthetic.md

@@ -0,0 +1,19 @@
+# Synthetic Phase 0 report
+
+Run on 2026-09-01 with `N=200`, in-memory SQLite, and three-run medians.
+
+| Path | Median | INSERTs |
+|---|---:|---:|
+| FactoryBot | 0.0521s | 400 |
+| `let_it_be` equivalent | 0.0126s | 2 |
+| factory_hoist | 0.0244s | 2 |
+
+- Record reduction: 99.5%
+- Dynamic-argument rate: 0.0% in the synthetic fixture
+- Tree depth: 1
+- Writing examples per file: 200
+- Fast Build separately measured above 5x FactoryBot
+
+The synthetic workload passes the 60% record-reduction gate, but factory_hoist is slower than the `let_it_be` equivalent. The design's stop decision remains undetermined because the target suite, target duration, mechanical `build_stubbed` result, depth distribution, and application code are not present.
+
+Reproduce with `bundle exec ruby bench/phase0_synthetic.rb`.

data/exe/factory_hoist

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+unless ARGV.shift == "advise"
+  warn "Usage: factory_hoist advise [SPEC_PATH ...]"
+  exit 1
+end
+
+require "rspec/core"
+require "factory_hoist"
+
+paths = ARGV.empty? ? ["spec"] : ARGV
+status = RSpec::Core::Runner.run(paths)
+FactoryHoist.advise(*paths)
+exit status

data/lib/factory_hoist/advisor.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module FactoryHoist
+  class Advisor
+    HOIST = /\bhoist\s*\(?\s*:(\w+)/
+    FACTORY_CALL = /\b(create|build|create_list|build_list)\s*\(\s*:(\w+)([^\n]*)\)/
+
+    def initialize(paths)
+      @paths = paths
+    end
+
+    def print(io)
+      findings = scan
+      if findings.empty?
+        io.puts "No factory hoist suggestions."
+      else
+        findings.each { |finding| io.puts finding }
+      end
+      print_runtime_stats(io)
+      findings
+    end
+
+    private
+
+    def scan
+      files.flat_map { |file| findings_for(file) }
+    end
+
+    def files
+      @paths.flat_map do |path|
+        File.directory?(path) ? Dir.glob(File.join(path, "**", "*_spec.rb")) : path
+      end.select { |path| File.file?(path) }.uniq.sort
+    end
+
+    def findings_for(file)
+      source = File.read(file)
+      unused = source.to_enum(:scan, HOIST).filter_map do
+        match = Regexp.last_match
+        name = match[1]
+        next if source.scan(/\b#{Regexp.escape(name)}\b/).size > 1
+
+        "#{file}:#{source[0...match.begin(0)].count("\n") + 1}: unused hoist :#{name}"
+      end
+      calls = source.scan(FACTORY_CALL).tally.filter_map do |(strategy, name, _arguments), count|
+        next unless count > 1
+
+        "#{file}: repeated #{strategy}(:#{name}) x#{count}; consider hoist(:#{name})"
+      end
+      unused + calls
+    end
+
+    def print_runtime_stats(io)
+      stats = FactoryHoist.stats.to_h
+      return if stats[:references].zero? && stats[:materializations].zero?
+
+      io.puts format(
+        "Runtime: %d materializations, %d references, %.1f%% degraded",
+        stats[:materializations], stats[:references], stats[:degradation_rate] * 100
+      )
+      stats[:materialization_costs].first(20).each do |key, seconds|
+        io.puts format("  %.3fs %s", seconds, key)
+      end
+      unused = stats[:materialization_costs].keys - stats[:reference_counts].keys
+      unused.each { |key| io.puts "  unused at runtime: #{key}" }
+    end
+  end
+end

data/lib/factory_hoist/bulk_writer.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module FactoryHoist
+  module BulkWriter
+    module_function
+
+    def call(name, count, traits, attributes)
+      unless defined?(::FactoryBot::Internal)
+        raise FactoryUnavailableError, "unsafe_bulk_insert requires factory_bot"
+      end
+
+      factory = ::FactoryBot::Internal.factory_by_name(name)
+      rows = Array.new(count) { ::FactoryBot.attributes_for(name, *traits, **attributes) }
+      return [] if rows.empty?
+
+      factory.build_class.transaction(requires_new: true) do
+        factory.build_class.insert_all!(rows)
+      end
+    rescue StandardError => error
+      index = failing_row(factory&.build_class, rows || [])
+      location = index ? " at row #{index}" : ""
+      raise BulkWriteError, "#{name} bulk insert failed#{location}: #{error.message}", cause: error
+    end
+
+    def failing_row(model, rows)
+      return unless model&.respond_to?(:transaction)
+
+      failed = nil
+      model.transaction(requires_new: true) do
+        rows.each_with_index do |row, index|
+          model.insert_all!([row])
+        rescue StandardError
+          failed = index
+          raise ::ActiveRecord::Rollback
+        end
+        raise ::ActiveRecord::Rollback
+      end
+      failed
+    rescue StandardError
+      nil
+    end
+    private_class_method :failing_row
+  end
+end

data/lib/factory_hoist/compatibility.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module FactoryHoist
+  module Compatibility
+    module_function
+
+    def warn_for_database_cleaner(io = $stderr)
+      return unless defined?(::DatabaseCleaner)
+
+      strategy = ::DatabaseCleaner[:active_record].strategy
+      return unless strategy.class.name.end_with?("Truncation")
+
+      io.puts "factory_hoist: DatabaseCleaner truncation removes hoisted rows; use transaction strategy"
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/factory_hoist/configuration.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module FactoryHoist
+  class Configuration
+    attr_accessor :factory_adapter, :paranoid_mode, :subxid_budget, :suite_seed
+
+    def initialize
+      @factory_adapter = nil
+      @paranoid_mode = false
+      @subxid_budget = 60
+      @suite_seed = 0
+    end
+  end
+end

data/lib/factory_hoist/database_snapshot.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "digest"
+require "set"
+
+module FactoryHoist
+  module DatabaseSnapshot
+    module_function
+
+    def call(scopes)
+      records = records_in(scopes.flat_map { |scope| scope.values.values })
+      return if records.empty?
+
+      rows = records.map do |record|
+        model = record.class.name || "table:#{record.class.table_name}"
+        primary_keys = Array(record.class.primary_key)
+        if primary_keys.empty?
+          identity = record.attributes
+          current = [identity, record.class.unscoped.where(identity).count]
+        else
+          identity = primary_keys.zip(Array(record.id)).to_h
+          current = record.class.unscoped.find_by(identity)&.attributes
+        end
+        [model, record.id || identity, current]
+      end.sort_by { |model, id, _attributes| [model, id.to_s] }
+      Digest::SHA256.hexdigest(Marshal.dump(rows))
+    end
+
+    def records_in(objects)
+      return [] unless defined?(::ActiveRecord::Base)
+
+      seen = Set.new
+      records = []
+      visit = lambda do |object|
+        return if object.nil? || seen.include?(object.object_id)
+
+        seen << object.object_id
+        case object
+        when ::ActiveRecord::Base
+          records << object if object.persisted?
+          associations = object.instance_variable_get(:@association_cache) || {}
+          associations.each_value { |association| visit.call(association.target) }
+        when Array
+          object.each { |value| visit.call(value) }
+        when Hash
+          object.each_value { |value| visit.call(value) }
+        end
+      end
+      objects.each { |object| visit.call(object) }
+      records
+    end
+    private_class_method :records_in
+  end
+end

data/lib/factory_hoist/deep_copy.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module FactoryHoist
+  module DeepCopy
+    module_function
+
+    def call(object)
+      Marshal.load(Marshal.dump(object))
+    end
+  end
+end

data/lib/factory_hoist/definition.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module FactoryHoist
+  Definition = Data.define(:name, :factory, :traits, :attributes, :block, :node_path) do
+    def materialize(context)
+      dynamic_attributes = if block
+        block.arity == 1 ? block.call(context) : context.__factory_hoist_evaluate__(&block)
+      else
+        {}
+      end
+      unless dynamic_attributes.is_a?(Hash)
+        raise ArgumentError, "hoist(:#{name}) block must return a Hash"
+      end
+
+      seed = Runtime.seed(node_path, name)
+      FactoryHoist.with_seed(seed) do
+        FactoryHoist.create(factory, *traits, **attributes, **dynamic_attributes)
+      end
+    rescue MaterializationError
+      raise
+    rescue StandardError => error
+      raise MaterializationError,
+        "#{node_path} hoist(:#{name}) failed: #{error.message}",
+        cause: error
+    end
+  end
+end