exwiw 0.9.6 → 0.9.8

data/lib/exwiw/determine_table_processing_order.rb

@@ -8,8 +8,18 @@ module Exwiw
 
     # @param tables [Array<Exwiw::TableConfig>] tables
     # @param logger [Logger, nil] receives a warning when a cycle has to be broken
+    # @param runtime_reverse_scope [Boolean] when true (mongodb), a table
+    #   declaring `reverse_scope` is ordered AFTER its `via` referencer tables:
+    #   the adapter builds the reverse filter from ids captured at runtime while
+    #   the referencers were dumped, so they must be processed first. Each arm's
+    #   own belongs_to edge back to the reverse-scoped table (the usual
+    #   `referencer.fk -> hub` relation) is inverted rather than kept, since the
+    #   declaration states ids flow referencer -> hub. False (the default)
+    #   preserves the historical belongs_to-only ordering — the SQL adapters
+    #   scope via subqueries and need the hub emitted before its referencers so
+    #   the INSERT output stays loadable in foreign-key order.
     # @return [Array<String>] sorted table names
-    def run(tables, logger: nil)
+    def run(tables, logger: nil, runtime_reverse_scope: false)
       return tables.map(&:name) if tables.size < 2
 
       ordered_table_names = []
@@ -19,31 +29,45 @@ module Exwiw
         acc[table.name] = table
       end
 
-      # Only belongs_to relations whose target is also in this run constrain the
-      # order. A belongs_to pointing at a table that is not being processed here
-      # — e.g. an embedded MongoDB collection (masked through its parent, never
-      # dumped on its own) or any table excluded from the run — is not something
-      # we can or need to order against, so it must never block resolution.
-      # Without this, such a dependency would stay unresolved forever and
-      # masquerade as a circular dependency, freezing every table that
-      # (transitively) references it.
+      reverse_scope_deps = runtime_reverse_scope ? compute_reverse_scope_dependencies(tables) : {}
+      dependencies_by_name = tables.each_with_object({}) do |table, acc|
+        acc[table.name] = compute_dependencies(table, reverse_scope_deps)
+      end
+
+      # Only relations whose target is also in this run constrain the order. A
+      # dependency pointing at a table that is not being processed here — e.g.
+      # an embedded MongoDB collection (masked through its parent, never dumped
+      # on its own) or any table excluded from the run — is not something we can
+      # or need to order against, so it must never block resolution. Without
+      # this, such a dependency would stay unresolved forever and masquerade as
+      # a circular dependency, freezing every table that (transitively)
+      # references it.
       present_names = table_by_name.keys.to_set
 
       loop do
         break if table_by_name.empty?
 
         resolvable = table_by_name.values.select do |table|
-          unresolved_dependencies(table, present_names, ordered).empty?
+          unresolved_dependencies(table.name, dependencies_by_name, present_names, ordered).empty?
         end
 
         if resolvable.empty?
           # No table has all its (in-run) dependencies satisfied, yet tables
-          # remain: the belongs_to graph has a genuine cycle and no strict
-          # topological order exists. Rather than aborting the whole export, break
-          # the cycle by emitting one cycle member; see pick_cycle_victim for how
-          # the member is chosen. Warn so the dropped constraint is visible.
-          victim = pick_cycle_victim(table_by_name.values, present_names, ordered)
-          warn_cycle_break(logger, victim, unresolved_dependencies(victim, present_names, ordered))
+          # remain: the dependency graph has a genuine cycle and no strict
+          # topological order exists.
+          #
+          # When a reverse_scope ordering edge participates in the cycle, there
+          # is no safe way out: emitting the reverse-scoped table before an arm
+          # would build its filter from missing state (silently dropping rows),
+          # so fail loudly instead of guessing.
+          detect_reverse_scope_cycle!(table_by_name, dependencies_by_name, reverse_scope_deps, present_names, ordered)
+
+          # Otherwise the cycle is a plain belongs_to cycle. Rather than
+          # aborting the whole export, break it by emitting one cycle member;
+          # see pick_cycle_victim for how the member is chosen. Warn so the
+          # dropped constraint is visible.
+          victim = pick_cycle_victim(table_by_name.values, dependencies_by_name, present_names, ordered)
+          warn_cycle_break(logger, victim, unresolved_dependencies(victim.name, dependencies_by_name, present_names, ordered))
           resolvable = [victim]
         end
 
@@ -67,13 +91,66 @@ module Exwiw
       table.belongs_tos.map(&:table_name)
     end
 
-    # The dependencies still blocking `table`: belongs_to targets that are part
-    # of this run, not yet ordered, and not the table itself (a self-referential
-    # belongs_to never blocks).
-    private_class_method def unresolved_dependencies(table, present_names, ordered)
-      compute_table_dependencies(table).uniq.select do |dep|
-        present_names.include?(dep) && !ordered.include?(dep) && dep != table.name
+    # reverse_scope ordering edges: reverse-scoped table name => its `via`
+    # referencer table names (the tables that must be processed before it).
+    private_class_method def compute_reverse_scope_dependencies(tables)
+      tables.each_with_object({}) do |table, acc|
+        next unless table.respond_to?(:reverse_scope)
+
+        arm_tables = (table.reverse_scope&.via || []).map(&:table).uniq
+        acc[table.name] = arm_tables if arm_tables.any?
+      end
+    end
+
+    # The ordering dependencies of `table`: its belongs_to targets — minus any
+    # belongs_to pointing at a reverse-scoped table that names `table` as a
+    # `via` arm (that edge is inverted: the arm feeds the reverse-scoped table
+    # its ids, so the arm goes first) — plus, when `table` itself is
+    # reverse-scoped, its `via` referencer tables.
+    private_class_method def compute_dependencies(table, reverse_scope_deps)
+      deps = compute_table_dependencies(table).reject do |dep|
+        reverse_scope_deps[dep]&.include?(table.name)
+      end
+      deps += reverse_scope_deps[table.name] || []
+      deps.uniq
+    end
+
+    # The dependencies still blocking `table_name`: dependency targets that are
+    # part of this run, not yet ordered, and not the table itself (a
+    # self-referential dependency never blocks).
+    private_class_method def unresolved_dependencies(table_name, dependencies_by_name, present_names, ordered)
+      dependencies_by_name.fetch(table_name).select do |dep|
+        present_names.include?(dep) && !ordered.include?(dep) && dep != table_name
+      end
+    end
+
+    # Raise when the stall is caused by a reverse_scope ordering edge: a
+    # reverse-scoped table and one of its `via` arms sit in the same non-trivial
+    # strongly-connected component, so no processing order can put every arm
+    # before the table. Typical shape: two reverse-scoped tables naming each
+    # other as arms, or an arm that (transitively) belongs_to the table it
+    # feeds. A plain belongs_to cycle (no reverse_scope edge involved) returns
+    # without raising, leaving the historical cycle-break to handle it.
+    private_class_method def detect_reverse_scope_cycle!(table_by_name, dependencies_by_name, reverse_scope_deps, present_names, ordered)
+      return if reverse_scope_deps.empty?
+
+      adjacency = table_by_name.each_key.each_with_object({}) do |name, acc|
+        acc[name] = unresolved_dependencies(name, dependencies_by_name, present_names, ordered)
       end
+      cyclic_names = strongly_connected_members(adjacency)
+
+      offenders = cyclic_names.select do |name|
+        (reverse_scope_deps[name] || []).any? { |arm| cyclic_names.include?(arm) }
+      end
+      return if offenders.empty?
+
+      details = offenders.sort.map { |name| "'#{name}' (via: #{(reverse_scope_deps[name] & cyclic_names.to_a).sort.join(', ')})" }
+      raise ArgumentError,
+            "reverse_scope creates an ordering cycle: #{details.join('; ')}. " \
+            "A reverse-scoped collection must be processed after all of its reverse_scope.via " \
+            "referencers, but these dependencies form a cycle with the belongs_to/reverse_scope " \
+            "graph (cycle members: #{cyclic_names.to_a.sort.join(', ')}). Remove one of the " \
+            "reverse_scope arms, or break the belongs_to edge that closes the cycle with `ignore: true`."
     end
 
     # Choose the next table to emit when the order is stuck in a cycle. Only
@@ -85,26 +162,27 @@ module Exwiw
     # collapsing to "match every row" (a cross-scope over-extraction risk for the
     # mongodb adapter); break remaining ties by fewest unresolved dependencies,
     # then by name, for determinism.
-    private_class_method def pick_cycle_victim(remaining, present_names, ordered)
+    private_class_method def pick_cycle_victim(remaining, dependencies_by_name, present_names, ordered)
       adjacency = remaining.each_with_object({}) do |table, acc|
-        acc[table.name] = unresolved_dependencies(table, present_names, ordered)
+        acc[table.name] = unresolved_dependencies(table.name, dependencies_by_name, present_names, ordered)
       end
       cyclic_names = strongly_connected_members(adjacency)
 
       candidates = remaining.select { |table| cyclic_names.include?(table.name) }
       candidates = remaining if candidates.empty? # defensive; a stall implies a cycle
 
-      anchored = candidates.select { |table| ordered_parent?(table, present_names, ordered) }
+      anchored = candidates.select { |table| ordered_parent?(table.name, dependencies_by_name, present_names, ordered) }
       pool = anchored.empty? ? candidates : anchored
 
-      pool.min_by { |table| [unresolved_dependencies(table, present_names, ordered).size, table.name] }
+      pool.min_by { |table| [unresolved_dependencies(table.name, dependencies_by_name, present_names, ordered).size, table.name] }
     end
 
-    # True when `table` has a belongs_to whose target was already ordered, so its
-    # extraction filter will be constrained rather than an unscoped full scan.
-    private_class_method def ordered_parent?(table, present_names, ordered)
-      compute_table_dependencies(table).any? do |dep|
-        dep != table.name && present_names.include?(dep) && ordered.include?(dep)
+    # True when `table_name` has a dependency whose target was already ordered,
+    # so its extraction filter will be constrained rather than an unscoped full
+    # scan.
+    private_class_method def ordered_parent?(table_name, dependencies_by_name, present_names, ordered)
+      dependencies_by_name.fetch(table_name).any? do |dep|
+        dep != table_name && present_names.include?(dep) && ordered.include?(dep)
       end
     end
 

data/lib/exwiw/explain_runner.rb

@@ -38,7 +38,13 @@ module Exwiw
       QueryAstBuilder.validate_scope!(dumpable_configs, table_by_name, @dump_target, @logger)
 
       @logger.debug("Determining table processing order...")
-      ordered_table_names = DetermineTableProcessingOrder.run(dumpable_configs, logger: @logger)
+      # Match the export's processing order (see Runner#run): mongodb orders a
+      # reverse-scoped collection after its `via` referencers.
+      ordered_table_names = DetermineTableProcessingOrder.run(
+        dumpable_configs,
+        logger: @logger,
+        runtime_reverse_scope: adapter.is_a?(Adapter::MongodbAdapter),
+      )
 
       total_size = ordered_table_names.size
       ordered_table_names.each_with_index do |table_name, idx|
@@ -68,7 +74,12 @@ module Exwiw
     private def load_table_config(klass)
       Dir[File.join(@schema_dir, "*.json")].map do |file|
         json = JSON.parse(File.read(file))
-        klass.from(json).reject_ignored_members!
+        begin
+          klass.from(json).reject_ignored_members!
+        rescue UnknownConfigKeyError => e
+          # `.from` knows the table, not the file; point at the offending file.
+          raise UnknownConfigKeyError, "#{file}: #{e.message}", e.backtrace
+        end
       end
     end
 

data/lib/exwiw/fake_data.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Exwiw
+  # Configuration for a column's `replace_with_fake_data` masking mode
+  # (see {RowTransformer}): the value is replaced with a fake value picked
+  # deterministically from a faker-generated pool, keyed by a hash of the
+  # `seed` column's value — so the same seed value always maps to the same
+  # fake value, across runs and adapters.
+  #
+  # `seed` names a column of the same table, either bare (`"id"`) or
+  # table-qualified (`"users.id"`). `type` selects the kind of fake value
+  # (see RowTransformer::FAKE_TYPES). `locale` optionally sets the faker
+  # locale used to build the pool (e.g. `"ja"`); nil uses faker's default.
+  class FakeData
+    include Serdes
+
+    attribute :seed, String
+    attribute :type, String
+    attribute :locale, optional(String), skip_serializing_if_nil: true
+  end
+end

data/lib/exwiw/mongodb_collection_config.rb

@@ -39,7 +39,30 @@ module Exwiw
     # `path`.
     attribute :embedded_in, optional(EmbeddedIn), skip_serializing_if_nil: true
 
+    # `reverse_scope` opts a collection into multi-referencer reverse scoping,
+    # mirroring the SQL TableConfig key (see Exwiw::ReverseScope): a
+    # global-identity collection referenced by many scoped collections is
+    # constrained to the union of the ids those referencers actually point at,
+    # instead of being dumped in full. Unlike the SQL adapters (which emit a
+    # UNION subquery), the mongodb adapter captures each `via` arm's column
+    # values at runtime while the referencer collection streams, so the
+    # reverse-scoped collection must be processed AFTER its referencers — see
+    # DetermineTableProcessingOrder (runtime_reverse_scope) and
+    # MongodbAdapter#reverse_scope_filter. User-configured and never emitted by
+    # MongoidSchemaGenerator; preserved across regeneration (see #merge).
+    attribute :reverse_scope, Serdes::OptionalType.new(ReverseScope), skip_serializing_if_nil: true
+
     def self.from(obj)
+      # Reject unknown keys before deserializing: Serdes silently drops them,
+      # which would turn a typo'd key — or a key only the SQL adapters support,
+      # like a field-level `raw_sql` — into a silent no-op (see
+      # Exwiw::StrictKeys). `comment` is a declared attribute here and on the
+      # nested belongs_to/field entries, so free-form notes stay accepted.
+      if obj.is_a?(Hash)
+        collection_name = obj["name"] || obj[:name]
+        StrictKeys.validate!(self, obj, owner: "collection '#{collection_name}'")
+      end
+
       instance = super
       instance.__send__(:validate_embedded!)
       instance.__send__(:validate_belongs_tos!)
@@ -89,6 +112,8 @@ module Exwiw
         # is kept.
         merged.comment = passed.comment || comment
         merged.embedded_in = passed.embedded_in
+        # User-owned, never regenerated: carry over from the existing config.
+        merged.reverse_scope = reverse_scope
 
         # Structural facts of each belongs_to come from the freshly generated
         # config (including a generator-derived `references`), but the user-owned
@@ -124,6 +149,12 @@ module Exwiw
 
     private def validate_embedded!
       return unless embedded?
+
+      if reverse_scope
+        raise ArgumentError,
+              "MongodbCollectionConfig '#{name}' is embedded_in '#{embedded_in.collection_name}'; " \
+              "reverse_scope must not be defined (an embedded config is never dumped on its own)."
+      end
       return if belongs_tos.empty?
 
       raise ArgumentError,

data/lib/exwiw/row_transformer.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Exwiw
+  # Applies the Ruby-process-side masking modes — `map` and
+  # `replace_with_fake_data` — to the rows streamed out of a SQL adapter's
+  # #execute. Unlike replace_with/raw_sql, which compile into the SELECT and
+  # run in the database, these run in the exwiw process, so they can execute
+  # arbitrary Ruby (`map`) or derive deterministic fake values (`fake data`).
+  #
+  # Built once per table (.build compiles the map procs, resolves seed column
+  # indexes, and pre-generates the fake-value pools), then #wrap decorates the
+  # adapter's StreamingResult: rows are transformed one at a time as the
+  # stream is drained, so the bounded-memory profile of the streaming dump is
+  # preserved. #size delegates to the underlying result, keeping the COPY
+  # path's upfront count and each_slice's allocation-hint COUNT identical to
+  # an unwrapped run.
+  #
+  # SQL adapters only: .build returns nil for configs without a `columns`
+  # list (MongodbCollectionConfig has `fields`; rails-managed tables have no
+  # columns), and for tables where no column carries a Ruby-side mode.
+  class RowTransformer
+    # Fake values are picked from a pool of this many pre-generated values.
+    # Distinct seed values beyond the pool size reuse pool entries (fine for
+    # fake data — determinism, not uniqueness, is the contract; uniqueness-
+    # sensitive types compose a 64-bit token on top, see FAKE_TYPES).
+    POOL_SIZE = 10_000
+
+    # Fixed Random seed for pool generation, so a pool is deterministic for a
+    # given faker gem version + locale.
+    POOL_RANDOM_SEED = 715_517
+
+    # Supported `replace_with_fake_data` types. `pool` builds one candidate
+    # value (called POOL_SIZE times under a seeded Faker random). Types with
+    # `compose` are uniqueness-sensitive: the pooled base alone would collide
+    # under a unique index at scale, so the final value composes the base with
+    # a 64-bit hex token derived from the same seed digest (collision
+    # probability at 5M distinct seeds ≈ 7e-7).
+    FAKE_TYPES = {
+      "human_name"   => { pool: -> { Faker::Name.name } },
+      "first_name"   => { pool: -> { Faker::Name.first_name } },
+      "last_name"    => { pool: -> { Faker::Name.last_name } },
+      "phone_number" => { pool: -> { Faker::PhoneNumber.phone_number } },
+      "address"      => { pool: -> { Faker::Address.full_address } },
+      "company_name" => { pool: -> { Faker::Company.name } },
+      "email"        => { pool: -> { Faker::Internet.username(specifier: 5..12) },
+                          compose: ->(base, token) { "#{base}.#{token}@example.com" } },
+      "username"     => { pool: -> { Faker::Internet.username(specifier: 5..12) },
+                          compose: ->(base, token) { "#{base}_#{token}" } },
+    }.freeze
+
+    # The `r` a map proc receives: read-only access to the current row's
+    # values by column name (`r['id']`). One instance is reused across all
+    # rows (zero per-row allocation) — do not retain it outside the proc.
+    class Row
+      def initialize(table_name, name_to_index)
+        @table_name = table_name
+        @name_to_index = name_to_index
+        @values = nil
+      end
+
+      attr_writer :values
+
+      def [](column_name)
+        index = @name_to_index[column_name]
+        unless index
+          raise ArgumentError,
+                "unknown column '#{column_name}' in map proc for table '#{@table_name}' " \
+                "(available: #{@name_to_index.keys.join(', ')})"
+        end
+        @values[index]
+      end
+    end
+
+    # Lazy Enumerable decorator returned by #wrap. Mirrors the adapters'
+    # StreamingResult contract (#size COUNT delegation, sized enum_for, #each
+    # returning self) so it is a drop-in for both write_inserts and
+    # to_copy_from_stdin.
+    class TransformedResult
+      include Enumerable
+
+      def initialize(inner, transformer)
+        @inner = inner
+        @transformer = transformer
+      end
+
+      def size
+        @inner.size
+      end
+      alias length size
+
+      def each
+        return enum_for(:each) { size } unless block_given?
+
+        @inner.each { |row| yield @transformer.transform(row) }
+        self
+      end
+    end
+
+    # -> RowTransformer | nil. nil when the table carries no Ruby-side mode,
+    # so the Runner can skip wrapping entirely (the unused path stays
+    # byte-identical and cost-free).
+    def self.build(table)
+      return nil unless table.respond_to?(:columns)
+
+      columns = table.columns
+      return nil if columns.nil? || columns.none? { |c| c.map || c.replace_with_fake_data }
+
+      new(table)
+    end
+
+    def self.require_faker!
+      require "faker"
+    rescue LoadError
+      raise LoadError,
+            "replace_with_fake_data requires the faker gem. " \
+            "Add `gem \"faker\"` to your Gemfile (it is not a runtime dependency of exwiw)."
+    end
+
+    # Pools are memoized per (type, locale): every column sharing a type+locale
+    # sees the same pool, which is what makes equal seed values map to equal
+    # fake values across tables and runs.
+    def self.fake_pool(type, locale)
+      @fake_pools ||= {}
+      @fake_pools[[type, locale]] ||= build_fake_pool(type, locale)
+    end
+
+    def self.build_fake_pool(type, locale)
+      spec = FAKE_TYPES.fetch(type)
+      previous_locale = Faker::Config.locale
+      previous_random = Faker::Config.random
+      Faker::Config.locale = locale if locale
+      Faker::Config.random = Random.new(POOL_RANDOM_SEED)
+      Array.new(POOL_SIZE) { spec[:pool].call.freeze }.freeze
+    ensure
+      Faker::Config.locale = previous_locale
+      Faker::Config.random = previous_random
+    end
+
+    def initialize(table)
+      @table_name = table.name
+      @name_to_index = {}
+      table.columns.each_with_index { |column, index| @name_to_index[column.name] = index }
+      @name_to_index.freeze
+      @row_accessor = Row.new(@table_name, @name_to_index)
+
+      self.class.require_faker! if table.columns.any?(&:replace_with_fake_data)
+
+      @transforms = table.columns.each_with_index.filter_map do |column, index|
+        if column.map
+          [index, compile_map(column)]
+        elsif column.replace_with_fake_data
+          [index, compile_fake(column, index)]
+        end
+      end
+      @replacement_buffer = Array.new(@transforms.size)
+    end
+
+    def wrap(results)
+      TransformedResult.new(results, self)
+    end
+
+    # Replacements are all computed from the original row before any is
+    # written back, so a map proc / fake seed always reads the pre-transform
+    # (post-SQL-masking) value regardless of column order. Rows are mutated in
+    # place when possible (each cursor yields a fresh Array per row), but
+    # sqlite3's Statement#each yields frozen rows — those are duped first.
+    def transform(row)
+      @transforms.each_with_index do |(_, callable), k|
+        @replacement_buffer[k] = callable.call(row)
+      end
+      row = row.dup if row.frozen?
+      @transforms.each_with_index do |(index, _), k|
+        row[index] = @replacement_buffer[k]
+      end
+      row
+    end
+
+    private def compile_map(column)
+      # eval is the documented contract of `map`: the schema config supplies a
+      # Ruby proc source and exwiw runs it. Configs are trusted local files
+      # (same trust level as the Gemfile); the README warns to only load
+      # trusted configs. Evaluated once per table, at dump time only — never
+      # during schema generation/regeneration.
+      evaluated =
+        begin
+          eval(column.map, TOPLEVEL_BINDING.dup, "(exwiw map for #{@table_name}.#{column.name})") # rubocop:disable Security/Eval
+        rescue StandardError, ScriptError => e
+          raise ArgumentError,
+                "map for column '#{@table_name}.#{column.name}' failed to eval: #{e.class}: #{e.message}"
+        end
+      unless evaluated.is_a?(Proc)
+        raise ArgumentError,
+              "map for column '#{@table_name}.#{column.name}' must evaluate to a Proc, got #{evaluated.class}"
+      end
+
+      row_accessor = @row_accessor
+      table_name = @table_name
+      column_name = column.name
+      lambda do |row|
+        row_accessor.values = row
+        begin
+          evaluated.call(row_accessor)
+        rescue StandardError => e
+          raise "map proc for column '#{table_name}.#{column_name}' raised: #{e.class}: #{e.message}"
+        end
+      end
+    end
+
+    private def compile_fake(column, column_index)
+      fake_data = column.replace_with_fake_data
+      spec = FAKE_TYPES.fetch(fake_data.type)
+
+      # Re-resolve the seed here, against the effective (post-ignore) columns:
+      # load-time validation sees the full column list, so a seed column that
+      # was ignore:true is only caught at dump time.
+      seed_column = fake_data.seed.delete_prefix("#{@table_name}.")
+      seed_index = @name_to_index[seed_column]
+      unless seed_index
+        raise ArgumentError,
+              "replace_with_fake_data for column '#{@table_name}.#{column.name}': " \
+              "seed '#{fake_data.seed}' does not resolve to an extracted column " \
+              "(is it ignore:true?)"
+      end
+
+      pool = self.class.fake_pool(fake_data.type, fake_data.locale)
+      compose = spec[:compose]
+
+      # NULL-preserving like replace_with: a NULL target stays NULL. A nil
+      # seed value hashes "" (deterministic). Seed values are normalized with
+      # to_s so sqlite's native Integer 123 and pg/mysql's string "123" pick
+      # the same fake value.
+      lambda do |row|
+        next nil if row[column_index].nil?
+
+        digest = Digest::SHA256.digest(row[seed_index].to_s)
+        base = pool[digest[0, 8].unpack1("Q>") % POOL_SIZE]
+        compose ? compose.call(base, digest[8, 8].unpack1("H*")) : base
+      end
+    end
+  end
+end

data/lib/exwiw/runner.rb

@@ -47,7 +47,16 @@ module Exwiw
       QueryAstBuilder.validate_scope!(dumpable_configs, table_by_name, @dump_target, @logger)
 
       @logger.info("Determining table processing order...")
-      ordered_table_names = DetermineTableProcessingOrder.run(dumpable_configs, logger: @logger)
+      # runtime_reverse_scope: the mongodb adapter builds a reverse-scoped
+      # collection's filter from ids captured while its `via` referencers were
+      # dumped, so those referencers must be processed first. The SQL adapters
+      # scope via subqueries and keep the historical belongs_to-only order
+      # (which also keeps their INSERT output loadable in foreign-key order).
+      ordered_table_names = DetermineTableProcessingOrder.run(
+        dumpable_configs,
+        logger: @logger,
+        runtime_reverse_scope: adapter.is_a?(Adapter::MongodbAdapter),
+      )
 
       clean_output_dir!
 
@@ -58,7 +67,7 @@ module Exwiw
       # replacement for the whole schema+inserts pass, after which the common
       # after-insert hook still runs. Everything before this point (validation,
       # scope check, ordering, output-dir clean) applies to both paths.
-      if use_mongodb_parallel?(adapter)
+      if use_mongodb_parallel?(adapter, configs)
         dump_mongodb_parallel(configs, table_by_name)
         run_after_insert_hook(adapter, ordered_table_names.size)
         return
@@ -86,9 +95,17 @@ module Exwiw
         # turning the fetched rows into SQL/JSONL, the rescue below can report
         # both the failing step and the exact extraction query that produced the
         # data being processed.
-        phase = "executing extraction query"
+        phase = "compiling row transforms (map/replace_with_fake_data)"
         begin
+          # Ruby-side masking (map / replace_with_fake_data): wrap the streamed
+          # results so rows are transformed as they are drained. nil (and thus
+          # a byte-identical, cost-free run) when no column opts in; covers
+          # both the INSERT and COPY branches below.
+          row_transformer = RowTransformer.build(table)
+
+          phase = "executing extraction query"
           results = adapter.execute(query_ast)
+          results = row_transformer.wrap(results) if row_transformer
           insert_idx = (idx + 1).to_s.rjust(3, '0')
 
           if @output_format == 'copy'
@@ -201,7 +218,7 @@ module Exwiw
     # target (the schedule is built around the scoped DAG), and a runtime that can
     # fork. Anything else falls back to the serial path (warning when the user
     # explicitly asked for parallelism but it cannot apply).
-    private def use_mongodb_parallel?(adapter)
+    private def use_mongodb_parallel?(adapter, configs)
       return false unless adapter.is_a?(Adapter::MongodbAdapter)
       return false unless @parallel_workers && @parallel_workers > 1
 
@@ -210,6 +227,15 @@ module Exwiw
         return false
       end
 
+      # A reverse-scoped collection consumes @state captured from its `via`
+      # referencers, an ordering constraint the parallel schedule (built around
+      # the belongs_to DAG only) does not express yet — a worker could dump the
+      # collection before its arms and silently drop rows. Run serially instead.
+      if configs.any? { |c| c.respond_to?(:reverse_scope) && c.reverse_scope&.via&.any? }
+        @logger.warn("--parallel-workers ignored: reverse_scope collections require the serial processing order; running serially.")
+        return false
+      end
+
       unless MongodbParallelDumper.available?
         @logger.warn("--parallel-workers ignored: fork is unavailable on this runtime; running serially.")
         return false
@@ -267,7 +293,12 @@ module Exwiw
         # considered during extraction. Done here (after loading from file)
         # rather than in `.from` so the schema generators keep the full config
         # and can preserve the ignored entries on regeneration.
-        klass.from(json).reject_ignored_members!
+        begin
+          klass.from(json).reject_ignored_members!
+        rescue UnknownConfigKeyError => e
+          # `.from` knows the table, not the file; point at the offending file.
+          raise UnknownConfigKeyError, "#{file}: #{e.message}", e.backtrace
+        end
       end
     end