exwiw 0.9.6 → 0.9.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a9938f5cd311ecefb5568ed27f35ed8594a9ba15e0041e241c423b25af12cba
-  data.tar.gz: f838bd892aecb7a717eac84f1bf52045cec0b6c1881c3a26c29bd4983c845326
+  metadata.gz: 2aa2a3c673085993f1f62cd055370eef814301b9298bc486d7f49f71e4470ccc
+  data.tar.gz: 04f5a73f8001d45e402a9d72839bcc824974e9aab4feff998cabc5b4311b762e
 SHA512:
-  metadata.gz: 17568187de281651d94abf50190bd0926a3a85eaaf468f9dcdc43b1254583c8cc416f5282e55de16f8af7a44dc1635f95d10f6a06b33de668ab98ace8e7eda79
-  data.tar.gz: 8530a5f2eaf0c15dda1c604e6bc65e923b8f91322990352e3de6ccb3c8dc832f2184e76496941cc4d64c49089b1639bc7b3743f20e79c3ad6083acff1b9c6f26
+  metadata.gz: c6a284caef2d3e5eb78d9252f36ef44a2f7e2d8531274ab13eedda9be0261cc9747319c211b556b17ebba1b471526df6bbea76670fed9005bca302f442582f26
+  data.tar.gz: fd3ec7cdf18b6db28b194a4fe694f09deb79a39428dc280c27709725f0619b24d6f8d361b02192558f20e51ad63b8028f565a3b5e98b9ab8d5dfeb57c51b73ef

data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.9.8] - 2026-07-09
+
+### Added
+
+- **The MongoDB adapter now supports `reverse_scope` (multi-referencer reverse scoping).** The `reverse_scope.via` key that `TableConfig` already offers for the SQL adapters is now accepted by `MongodbCollectionConfig` with the same shape and semantics: a global-identity collection with no `belongs_to` path to the dump target, referenced by several scoped collections, is constrained to the union of the ids its enumerated referencer arms actually point at instead of being dumped in full. Where SQL emits a `UNION` subquery, the mongodb adapter captures each arm's foreign-key values **at runtime** while the referencer collection streams (the existing parent-id propagation mechanism, extended to via-arm columns; `null`s are dropped per arm, array-valued columns contribute one id per element, and captured values keep their native BSON types). Because of that runtime capture, `DetermineTableProcessingOrder` gains a mongodb-only mode that orders a reverse-scoped collection **after** all of its `via` referencers (inverting an arm's own `belongs_to` edge back to the collection) and aborts with a clear error when the arms create a genuine ordering cycle; the SQL processing order is unchanged. Arm hygiene mirrors SQL (an unknown / embedded / undumped / unscoped referencer is skipped with a warning rather than silently widening the dump), a collection with its own `belongs_to` path to the target keeps that scope (`reverse_scope` is ignored, as in SQL), satellites of the reverse-scoped collection tighten automatically, `exwiw explain` shows the real filter shape with a placeholder id, and `--parallel-workers` falls back to serial with a warning when a reverse-scoped collection is present (the parallel schedule does not express the new ordering constraint yet). Masking/fields behavior is unchanged, and the key stays user-owned: never emitted by the schema generator and preserved across regeneration.
+
+### Changed
+
+- **Unknown keys in schema config JSON are now rejected on load instead of being silently dropped.** Serdes deserialization is lenient, so a key that matched no declared attribute was discarded without a word — turning a typo (`reverse_scop`, `bulk_insert_chunk_sise`) or a key another adapter supports but this one does not (`raw_sql`/`map` on a MongoDB field; `reverse_scope` on a MongoDB collection before this release) into a silent no-op: the dump ran and the requested masking/scoping simply never happened. `TableConfig.from` / `MongodbCollectionConfig.from` now validate the raw hash against the declared attributes — including the nested `belongs_tos` / `columns` / `fields` / `reverse_scope` / `embedded_in` / `replace_with_fake_data` entries — and raise `Exwiw::UnknownConfigKeyError` (an `ArgumentError` subclass) naming the key(s), the table/collection, the nested position, and the allowed keys; `export`/`explain` prepend the offending file path. This is a deliberate hard error with no opt-out: every declared key still passes — including the documentation-only `comment` on table/collection configs and their `belongs_tos`/`columns`/`fields` entries, which remains the supported place for free-form notes — so a config that only uses supported keys is unaffected, while anything now rejected was already being ignored. If a config carries stray keys, remove them or fold them into `comment`.
+
+## [0.9.7] - 2026-07-08
+
+### Added
+
+- **`map` masking mode (SQL adapters).** The long-promised `map` column key is now implemented: its value is evaluated once as Ruby and must yield a `Proc`, which is then called for every fetched row with a row accessor (`r['column_name']` reads any column's fetched value) and whose return value replaces the column value in the dump. Unlike `replace_with`/`raw_sql` (which compile into the `SELECT` and run in the database), `map` runs in the exwiw process — it can express transforms SQL cannot, at a measured cost of well under a microsecond per row. There is no automatic NULL preservation (the proc receives `nil` and decides), the key is exclusive with the other masking keys on the same column, and it executes arbitrary Ruby from the schema config — only load trusted configs. mysql/postgresql/sqlite only (the MongoDB adapter silently drops the key, like `raw_sql`); both the INSERT and the PostgreSQL COPY output paths are covered, and the transform streams with the existing bounded-memory dump (no change to the memory profile).
+- **`replace_with_fake_data` masking mode (SQL adapters).** Replaces a column with realistic fake data from the [faker](https://github.com/faker-ruby/faker) gem, picked **deterministically** by a SHA-256 hash of a seed column's value — `{ "seed": "users.id", "type": "human_name" }` maps the same id to the same fake name across tables, runs, and adapters (seed values are `to_s`-normalized, so sqlite's integer ids agree with pg/mysql's string form). NULL targets stay NULL (like `replace_with`); an optional `"locale"` picks the faker locale (e.g. `"ja"`). Supported types: `human_name`, `first_name`, `last_name`, `phone_number`, `address`, `company_name`, plus uniqueness-sensitive `email`/`username`, which embed a 64-bit hex token from the seed hash so unique indexes survive multi-million-row dumps. Values are drawn from a pool of 10,000 candidates pre-generated per (type, locale) under a fixed seed — this keeps the per-row cost at ~1.5µs per fake column, ≈ +8s per 5M rows (a naive per-row faker call is ~30µs), and makes values stable for a given faker version + locale (upgrading faker remaps them). faker is deliberately **not** a runtime dependency: add `gem "faker"` to the consuming Gemfile. Benchmarks and design notes in `docs/row-transform-masking-notes.md` / `script/bench_row_transform.rb`.
+
 ## [0.9.6] - 2026-07-08
 
 ### Added

data/README.md

@@ -451,12 +451,12 @@ This is an example of the one table schema:
     "primary_key": "id",
     "filter": "users.id > 0",
     "bulk_insert_chunk_size": 1000,
-    "belongs_to": [{
-        "name": "companies",
+    "belongs_tos": [{
+        "table_name": "companies",
         "foreign_key": "company_id"
     }],
     "columns": [{
-        "name": "id",
+        "name": "id"
     }, {
         "name": "email",
         "replace_with": "user{id}@example.com"
@@ -468,6 +468,12 @@ This is an example of the one table schema:
 
 `--schema-dir` will use all json files in the specified directory.
 
+#### Unknown keys are rejected
+
+Loading a table/collection config with a key that no declared attribute accepts is an **error** (`Exwiw::UnknownConfigKeyError`, an `ArgumentError` subclass) naming the key, the table/collection, the offending file, and the allowed keys. This also applies to the nested `belongs_tos` / `columns` / `fields` / `reverse_scope` / `embedded_in` / `replace_with_fake_data` entries. Previously such keys were silently dropped, which turned a typo (`reverse_scop`) — or a key another adapter supports but this one does not (e.g. `raw_sql` on a MongoDB field) — into a silent no-op: the config loaded, the dump ran, and the requested masking/scoping simply never happened.
+
+For free-form annotations, use the `comment` key — it is a declared, documentation-only attribute on table/collection configs and on their `belongs_tos` / `columns` / `fields` entries, so it always passes (see [Ignore / annotate a column or `belongs_to`](#ignore--annotate-a-column-or-belongs_to)).
+
 ### Output format
 
 By default, exwiw generates `INSERT` statements. For PostgreSQL, you can pass `--output-format=copy` to generate `COPY FROM stdin` format instead, which is significantly faster for bulk loading.
@@ -680,6 +686,7 @@ Notes:
 - **NULLs are excluded** per arm (`IS NOT NULL`).
 - **Satellites need no config.** A table that `belongs_to` the reverse-scoped table (e.g. `end_users.id → users.id`, or `identities.user_id → users.id`) tightens to the kept ids automatically through the normal cascade — only the reverse-scoped table itself declares `reverse_scope`. The cascade is **multi-hop**, so a table several `belongs_to` hops below the reverse-scoped table (e.g. `end_user_profiles → end_users → users`) also tightens automatically, with no config of its own.
 - Works in both single-target and scope-column mode. In single-target mode there is no scope-column pre-flight (`validate_scope!`), so a satellite the cascade cannot resolve to a single scopable parent (e.g. it `belongs_to` two scopable hubs) is dumped in full with a warning rather than aborting. Polymorphic foreign keys are not eligible as anchors (the named `column` is always a concrete column).
+- **The MongoDB adapter supports `reverse_scope` too** — same config shape and semantics, but the id set is captured at runtime instead of being emitted as a `UNION` subquery. See [`reverse_scope` on collections](#reverse_scope-on-collections) under MongoDB notes.
 
 ### Why a JOIN, not `IN (subquery)`
 
@@ -788,19 +795,102 @@ If it used with `replace_with`, `replace_with` will be ignored.
 
 #### `map`
 
-XXX: TODO
-
-Given value will be evaluated as Ruby code, and treated as the proc.
+The value is evaluated as Ruby code once (per table, at dump time), must yield a
+`Proc`, and the proc is called for every fetched row. Its return value replaces
+the column value in the dump:
 
-```
-"map": "proc { |r| 'user' + v['id'].to_s + '@example.com' }"
+```jsonc
+{ "name": "email", "map": "proc { |r| 'user' + r['id'].to_s + '@example.com' }" }
 ```
 
 which is equivalent to `"replace_with": "user{id}@example.com"`.
 
-Notice this is the most powerful option, but you should be careful to use this option.
-Because this transformation occured on exwiw process, so much slower than other options.
-Most of case, this option is not recommended.
+- `r['column_name']` reads any column of the current row — the value as fetched
+  from the database (i.e. after SQL-side masking such as another column's
+  `replace_with`, before Ruby-side transforms). `r` is only valid inside the
+  call; do not retain it.
+- Return a `String`, `Numeric`, or `nil`. Unlike `replace_with` there is **no
+  automatic NULL preservation** — the proc receives `nil` and decides.
+- `map` is exclusive with the other masking keys on the same column
+  (`raw_sql` / `replace_with` / `replace_with_fake_data`).
+- SQL adapters only. On the MongoDB adapter the key is rejected on load, like
+  `raw_sql` (see [Unknown keys are rejected](#unknown-keys-are-rejected)).
+  Because the transform runs in the exwiw process, it is invisible to
+  `explain`.
+
+**Security note**: `map` executes arbitrary Ruby from the schema config. Treat
+config files with the same trust as your Gemfile — only load trusted configs.
+
+This is the most powerful option, but it runs per row in the exwiw process
+rather than in the database. The measured dispatch cost is small, though
+(~0.6–0.8µs/row plus whatever the proc body does — see
+[`docs/row-transform-masking-notes.md`](docs/row-transform-masking-notes.md)).
+Prefer `replace_with`/`raw_sql` when they can express the transform; reach for
+`map` when they cannot.
+
+#### `replace_with_fake_data`
+
+Replaces the value with realistic-looking fake data generated by the
+[faker](https://github.com/faker-ruby/faker) gem, picked **deterministically**
+from the value of a seed column — the same seed value always maps to the same
+fake value, across tables, runs, and adapters:
+
+```jsonc
+{
+  "name": "name",
+  "replace_with_fake_data": { "seed": "users.id", "type": "human_name" }
+}
+```
+
+- `seed` names a column of the same table, bare (`"id"`) or table-qualified
+  (`"users.id"`). The seed value is hashed (SHA-256, after `to_s`
+  normalization, so sqlite's integer `123` and postgres/mysql's string `"123"`
+  agree) and the hash picks the fake value. Use a stable identifier (integer or
+  string primary key) as the seed; float/decimal/binary columns are discouraged
+  because their text forms differ per adapter. A `NULL` seed value hashes `""`
+  (still deterministic).
+- Like `replace_with`, it **preserves NULL** in the target column.
+- `locale` (optional) sets the faker locale used to generate the candidate
+  values, e.g. `{ "seed": "id", "type": "human_name", "locale": "ja" }` produces
+  Japanese names.
+- Supported `type`s:
+
+  | type | example output |
+  |------|----------------|
+  | `human_name` | `Adrianna Kilback` |
+  | `first_name` | `Adrianna` |
+  | `last_name` | `Kilback` |
+  | `phone_number` | `(555) 123-4567` |
+  | `address` | `282 Kevin Brook, Imogeneborough, CA 58517` |
+  | `company_name` | `Hirthe-Ritchie` |
+  | `email` | `cliff.fay.9d6b804eff5a3f57@example.com` |
+  | `username` | `cliff.fay_9d6b804eff5a3f57` |
+
+- Values are drawn from a pool of 10,000 pre-generated candidates per
+  (type, locale), so distinct seeds can share a fake value. The
+  uniqueness-sensitive types (`email`, `username`) additionally embed a 64-bit
+  hex token derived from the seed hash, so they stay collision-free under a
+  unique index even at millions of rows (collision probability at 5M distinct
+  seeds ≈ 7e-7) and always use the `example.com` domain.
+- **Determinism caveat**: values are stable for a given faker gem version +
+  locale. Upgrading faker (or changing `locale`) regenerates the pool and maps
+  seeds to different values. The seed→value mapping itself never changes within
+  one version.
+- The faker gem is **not** a runtime dependency of exwiw — add `gem "faker"` to
+  your Gemfile to use this mode (exwiw raises a clear error otherwise).
+- Exclusive with the other masking keys on the same column. SQL adapters only
+  (the MongoDB adapter rejects the key on load, see
+  [Unknown keys are rejected](#unknown-keys-are-rejected)), and invisible to
+  `explain`.
+
+**Performance**: this is a per-row Ruby transform, measured at ~1.5–1.6µs/row
+per fake column (so ≈ +8s per 5M rows per column; ~+40% against a local sqlite
+fetch — the worst case — and proportionally less against a network database,
+where the fetch dominates). Values are drawn from a pool pre-generated once,
+not by calling faker per row (which would be ~20× slower). Memory is
+unaffected: the transform streams with the dump. See
+[`docs/row-transform-masking-notes.md`](docs/row-transform-masking-notes.md)
+for the benchmark, and `script/bench_row_transform.rb` to measure on your data.
 
 ### MongoDB notes
 
@@ -826,9 +916,39 @@ The MongoDB adapter is experimental. To use it:
   mongosh "mongodb://localhost/app_dev" dump/insert-000-schema.js
   ```
 - Unlike SQL adapters, the MongoDB adapter does not emit `delete-*.jsonl` files (drop the database / collection yourself before importing if needed).
-- `raw_sql` is not supported (the `MongodbField` schema does not declare it; any `raw_sql` keys in scenario JSON are silently dropped on load). Use `replace_with` for masking.
+- `raw_sql`, `map`, and `replace_with_fake_data` are not supported (the `MongodbField` schema does not declare them; such keys in a config are rejected on load — see [Unknown keys are rejected](#unknown-keys-are-rejected)). Use `replace_with` for masking.
 - The MongoDB adapter does not support the collection-level `filter` field (it raises `NotImplementedError` if set, since the SQL-string filter cannot be applied to MongoDB).
 
+#### `reverse_scope` on collections
+
+[Multi-referencer reverse scoping](#reverse-scope-for-multi-referencer-tables-reverse_scope) works on `MongodbCollectionConfig` with the same config shape and the same semantics as the SQL adapters — a global-identity collection (say `accounts`) with no `belongs_to` path to the dump target, but referenced by several scoped collections, is constrained to the union of the ids those referencers actually point at instead of being dumped in full:
+
+```json
+{
+  "name": "accounts",
+  "primary_key": "_id",
+  "reverse_scope": {
+    "via": [
+      { "table": "articles", "column": "author_account_id" },
+      { "table": "invitations", "column": "invitee_account_id" }
+    ]
+  },
+  "belongs_tos": [],
+  "fields": [{ "name": "_id" }, { "name": "name" }]
+}
+```
+
+Where the SQL adapters emit a `UNION` subquery, MongoDB has no cross-collection joins, so the adapter captures each arm's column values **at runtime** while the referencer collection streams (the same mechanism that already propagates parent ids to children), then filters the reverse-scoped collection with `{"_id": {"$in": [<union of captured ids>]}}`. Consequences of that runtime capture:
+
+- **Processing order**: a reverse-scoped collection is dumped **after** all of its `via` referencers (an arm's own `belongs_to` back to the reverse-scoped collection is inverted rather than kept — the declaration states ids flow referencer → collection). If the arms form a genuine ordering cycle with the `belongs_to` graph, the export aborts with an error naming the cycle members. SQL processing order is unchanged (its INSERT output must stay loadable in foreign-key order).
+- **Arm hygiene mirrors SQL**: an arm whose referencer is unknown, embedded, not dumped, or itself unscoped (no path to the dump target and no `reverse_scope` of its own) is **skipped with a warning** — an unscoped referencer's ids span every scope and would silently widen the dump. Per-arm `null`/absent foreign keys are dropped (the SQL `IS NOT NULL`), an array-valued foreign-key column contributes one id per element, and captured values keep their native BSON types (an `ObjectId` foreign key matches an `ObjectId` `_id` with no coercion).
+- **Precedence mirrors SQL**: a collection with its own `belongs_to` path to the dump target is scoped by that path; a `reverse_scope` declared on it is ignored.
+- **Satellites need no config**, as in SQL: a collection that `belongs_to` the reverse-scoped collection tightens to the kept ids automatically through the ordinary captured-parent-id mechanism.
+- **`--parallel-workers` falls back to serial** (with a warning) when any collection declares `reverse_scope` — the parallel schedule does not express the referencers-first ordering constraint yet.
+- **`exwiw explain`** shows the real `{"_id": {"$in": [...]}}` filter shape with a placeholder id, like the other runtime-captured scopes.
+
+Masking (`replace_with`) and `fields` behavior on a reverse-scoped collection are unchanged. Like the SQL key, `reverse_scope` is user-owned: `exwiw:mongoid:schema:generate` never emits it and regeneration preserves a hand-added value.
+
 #### Embedded documents
 
 MongoDB models often store one-to-many relationships as embedded subdocument arrays (e.g. `users` documents with a `posts: [...]` field). To mask fields inside embedded subdocuments, declare a separate config with `embedded_in`:

data/docs/row-transform-masking-notes.md

@@ -0,0 +1,156 @@
+# Ruby-side masking (`map` / `replace_with_fake_data`): design & benchmark notes
+
+Companion to [`sql-dump-optimization-notes.md`](./sql-dump-optimization-notes.md).
+That document records how the SQL dump path became a bounded-memory streaming
+pipeline; this one records the cost of the first **per-row Ruby work** added on
+top of it — the `RowTransformer` that implements the `map` and
+`replace_with_fake_data` masking modes — and the design decisions the numbers
+drove.
+
+The reproducible harness is `script/bench_row_transform.rb`. The correctness
+anchors are `spec/row_transformer_spec.rb` (determinism contract) and
+`spec/insert_output_snapshot_spec.rb` (byte-exact output for `map`).
+
+## Why these modes cost anything at all
+
+`replace_with` / `raw_sql` compile into the `SELECT` and run **in the
+database**; the Ruby pipeline (streaming fetch → `write_inserts`) previously
+did zero per-row transform work. `map` (arbitrary Ruby proc) and
+`replace_with_fake_data` (faker values) cannot be pushed into SQL, so they run
+in the exwiw process, per row, between the cursor and the INSERT/COPY writer:
+
+```
+adapter.execute --> StreamingResult --(RowTransformer::TransformedResult#each)--> write_inserts / to_copy_from_stdin
+```
+
+The wrapper delegates `#size` (so the COPY path's upfront count and
+`each_slice`'s allocation-hint COUNT are unchanged) and transforms rows one at
+a time off `#each`, so the bounded-memory profile of the streaming dump is
+preserved. When no column opts in, `RowTransformer.build` returns nil and the
+pipeline is byte-for-byte the pre-existing one.
+
+## Design decisions the measurements drove
+
+### Fake values come from a pre-generated pool, not per-row faker calls
+
+A naive deterministic design — per row, seed faker's RNG with the hash and
+call the generator —
+
+```ruby
+Faker::Config.random = Random.new(seed_hash)
+Faker::Name.name
+```
+
+measures **~30 µs/row** (I18n lookups + regex templating per call). At 5M rows
+that is ~150 s for one column: unacceptable.
+
+Instead, `RowTransformer` pre-generates a pool of `POOL_SIZE = 10_000`
+candidate values per `(type, locale)` under a fixed RNG seed (~0.2 s, once),
+and per row only hashes the seed value and indexes the pool:
+
+```ruby
+digest = Digest::SHA256.digest(seed_value.to_s)
+pool[digest[0, 8].unpack1("Q>") % POOL_SIZE]
+```
+
+That is ~1.4 µs/row — **~21× cheaper** — and just as deterministic (values are
+stable for a given faker version + locale; the pool regenerates identically).
+
+### One SHA-256 digest supplies both the pool index and the uniqueness token
+
+`Zlib.crc32` is ~16× faster than SHA-256 (0.055 vs 0.87 µs/op), but 32 bits is
+unusable for the uniqueness token the `email`/`username` types embed: a
+birthday collision is even money at ~77k distinct seeds, far below the
+multi-million-row target. One SHA-256 per row provides 64 bits for the pool
+index (bytes 0–7) and an independent 64-bit hex token (bytes 8–15) whose
+collision probability at 5M distinct seeds is ≈ 7e-7. The hash is not the
+bottleneck (see numbers below), so there is no fast-path variant.
+
+### Zero-allocation row accessor for `map`
+
+The proc receives a single reused accessor object (`r['column']` resolves
+through a frozen name→index Hash built once per table), not a per-row Hash of
+the whole row. Replacements are computed from the original row before any is
+written back, so transformed columns can read each other's *pre*-transform
+values regardless of column order. Rows are mutated in place when the driver
+allows it; sqlite3's `Statement#each` yields **frozen** rows, which are duped
+first (the one extra allocation on that adapter).
+
+## Measurements
+
+Environment: Apple Silicon (arm64, 64 GB), Ruby 4.0.5, faker 3.8.0, sqlite
+adapter for serialization. 8-column rows, ~211 B/row of output. Run:
+
+```bash
+BENCH_ROWS=2000000 bundle exec ruby script/bench_row_transform.rb
+BENCH_ROWS=5000000 BENCH_PART_A=0 bundle exec ruby script/bench_row_transform.rb  # E2E only
+```
+
+### Part A — serialization path only (2M rows, 422 MB output)
+
+The rows are pre-materialized, so the delta is exactly the transform cost on
+the `write_inserts` path — the *most pessimistic* relative view, since a real
+dump also pays the DB fetch.
+
+| variant | wall | vs baseline | per row |
+|---|---|---|---|
+| baseline (no transform) | 6.99 s (286k rows/s) | — | — |
+| `map` ×1 column | 8.27 s | +18% | +0.64 µs |
+| fake ×1 column (email) | 10.17 s | +45% | +1.59 µs |
+| fake ×3 columns | 13.85 s | +98% | +3.43 µs (~1.1 µs/col) |
+
+### Per-operation microbench
+
+| operation | µs/op |
+|---|---|
+| SHA-256 digest → u64 index + hex token | 0.87 |
+| `Zlib.crc32` (comparison only) | 0.055 |
+| fake pipeline, transform 1 row (email) | 1.42 |
+| `map` dispatch, transform 1 row | 0.83 |
+| naive per-row `Faker::Name.name` (rejected design) | ~30 |
+
+### Part B — end-to-end against live sqlite (5M rows, ~1.06 GB output)
+
+`execute` + wrap + `write_inserts`, fresh process (`BENCH_PART_A=0`; see
+pitfalls below):
+
+| variant | wall | vs baseline | per row |
+|---|---|---|---|
+| baseline | 19.97 s (250k rows/s) | — | — |
+| fake ×1 column (email) | 27.98 s | +40% | +1.60 µs |
+
+RSS stayed flat at ~70–100 MB for both variants across the whole 5M-row /
+1 GB dump — the transform does not disturb the streaming memory profile.
+
+The 2M-row E2E run reproduces the same per-row cost (+1.55 µs/row).
+
+### Reading the numbers
+
+- **The stable metric is µs/row per masked column**: ~0.6–0.8 µs for `map`
+  (plus whatever the user's proc does), ~1.5–1.6 µs for fake data
+  (SHA-256 + pool lookup + compose + the sqlite frozen-row dup).
+- At **5M rows, one fake column costs ~8 s** of wall clock.
+- The relative percentages above are worst-case: a local sqlite fetch is the
+  fastest possible source (baseline ~4 µs/row), so +1.6 µs reads as +40%.
+  Against a network mysql/postgresql source the same absolute overhead is a
+  much smaller fraction; on the fully-diluted end (2M E2E measured in a
+  process with a large heap) it read as +21%. Unused tables/columns cost
+  exactly zero (`build` returns nil; nothing is wrapped).
+
+## Benchmarking pitfalls found on the way
+
+Recorded because both would silently corrupt a rerun:
+
+1. **A 10 ms `ps` RSS sampler is catastrophic on a large heap.** The
+   `script/bench_sql_dump.rb`-style background sampler forks the whole process
+   per sample; with the ~1 GB rows array a 2M-row `write_inserts` went from
+   10.8 s to **502 s**. This script reports before/after RSS (2 forks per
+   phase) instead; peak-transient capture matters less here because the
+   transform adds no table-sized structure.
+2. **The first measured variant absorbs one-time heap expansion.** With only a
+   partial warm pass, the baseline (measured first) ran ~15% slower than the
+   later variants — enough to make `map` appear *faster* than no transform.
+   The script now does a full-size unmeasured warm pass first. Relatedly,
+   running Part A's materialized array before Part B in one process inflates
+   Part B's GC costs (the 5M E2E overhead read +6.0 µs/row instead of
+   +1.6 µs/row); hence `BENCH_PART_A=0` for clean E2E numbers.

data/lib/exwiw/adapter/mongodb_adapter.rb

@@ -413,18 +413,34 @@ module Exwiw
       # The distinct set of this collection's fields that downstream children
       # constrain on (each child belongs_to's `references`, defaulting to this
       # collection's primary_key), with primary_key always included so the
-      # historical primary-key-keyed propagation keeps working.
+      # historical primary-key-keyed propagation keeps working. A collection
+      # named as a `reverse_scope.via` referencer additionally captures the
+      # arm's foreign-key column, so the reverse-scoped collection (processed
+      # later) can constrain itself to the ids this collection points at.
       private def propagation_keys_for(config, config_by_name)
         referenced = config_by_name.each_value.flat_map do |child|
           next [] if child.embedded?
 
-          child.belongs_tos
+          keys = child.belongs_tos
             .select { |relation| relation.table_name == config.name }
             .map { |relation| relation.references || config.primary_key }
+
+          reverse_scope_arms_of(child).each do |via|
+            keys << via.column if via.table == config.name
+          end
+
+          keys
         end
         ([config.primary_key] + referenced).uniq
       end
 
+      # The `reverse_scope.via` arms of `config`, or [] when it declares none.
+      private def reverse_scope_arms_of(config)
+        return [] unless config.respond_to?(:reverse_scope)
+
+        config.reverse_scope&.via || []
+      end
+
       # Build the scoping filter for a non-target collection from its belongs_to
       # parents' captured ids. Each belongs_to is constrained by the parent field
       # the FK references (`relation.references`, default the parent primary_key);
@@ -476,6 +492,24 @@ module Exwiw
       private def related_collection_filter(config, config_by_name, dump_target)
         genuine = genuine_scope_set(config_by_name, dump_target.table_name)
 
+        # Opt-in multi-referencer reverse scope (MongodbCollectionConfig
+        # #reverse_scope), mirroring the SQL adapters' semantics: it applies only
+        # to a collection with no belongs_to path to the dump target (exactly
+        # when SQL's reverse extraction is attempted — a genuinely scoped
+        # collection keeps its belongs_to scope and reverse_scope is ignored),
+        # and when it applies it IS the scope filter, replacing the
+        # reference-parent strict-AND fallback. When no arm survives, fall
+        # through to the historical behavior, as SQL falls back to dump-all.
+        if !genuine.include?(config.name) && reverse_scope_arms_of(config).any?
+          filter = reverse_scope_filter(config, config_by_name, genuine)
+          return filter unless filter.nil?
+        elsif genuine.include?(config.name) && reverse_scope_arms_of(config).any?
+          @logger.debug(
+            "  Collection '#{config.name}' declares reverse_scope but is genuinely scoped " \
+            "via belongs_to; reverse_scope is ignored (same precedence as the SQL adapters)."
+          )
+        end
+
         genuine_clauses = []
         reference_clauses = []
         config.belongs_tos.each do |relation|
@@ -509,6 +543,88 @@ module Exwiw
         { config.primary_key => { "$in" => [] } }
       end
 
+      # Build the `pk $in <union of referenced ids>` filter for a reverse-scoped
+      # collection (MongodbCollectionConfig#reverse_scope). Each `via` arm names
+      # a referencer collection and the foreign-key column on it that points at
+      # this collection's primary key; the referencer was dumped earlier under
+      # its own scope (DetermineTableProcessingOrder orders every arm before the
+      # reverse-scoped collection) and #execute captured the arm column's values
+      # into @state, so the union here holds only in-scope ids. Values are used
+      # exactly as captured (native BSON — ObjectId FKs stay ObjectIds, string
+      # FKs stay strings), array-valued columns are flattened (one referenced id
+      # per element), and nil/absent FKs are dropped, mirroring the SQL arms'
+      # `IS NOT NULL`.
+      #
+      # An arm is skipped with a warning when its referencer is unknown,
+      # embedded, produced no captured state (not dumped — e.g. ignore:true), or
+      # is itself unscoped (neither genuinely scoped nor reverse-scoped): an
+      # unscoped referencer's captured ids span every scope and would silently
+      # widen the dump, exactly the case the SQL adapters skip. Returns nil when
+      # no arm survives, letting the caller fall through to the historical
+      # behavior (SQL parity: dump-all fallback).
+      #
+      # In `explain` placeholder mode there is no captured state; a placeholder
+      # id keeps the real filter shape (`pk $in [...]`) so index selection is
+      # reported correctly.
+      private def reverse_scope_filter(config, config_by_name, genuine)
+        ids = []
+        any_arm = false
+
+        reverse_scope_arms_of(config).each do |via|
+          referencer = config_by_name[via.table]
+          if referencer.nil? || referencer.embedded?
+            @logger.warn(
+              "  #{config.name}.reverse_scope references #{referencer.nil? ? 'unknown' : 'embedded'} " \
+              "collection '#{via.table}'; skipping arm."
+            )
+            next
+          end
+
+          unless genuine.include?(via.table) || reverse_scope_arms_of(referencer).any?
+            @logger.warn(
+              "  #{config.name}.reverse_scope arm '#{via.table}.#{via.column}' is not scoped; " \
+              "skipping it (an unscoped arm would union ids from every scope back). " \
+              "Make '#{via.table}' scopable or remove it from reverse_scope.via."
+            )
+            next
+          end
+
+          if @explain_placeholder
+            any_arm = true
+            ids << explain_placeholder_id
+            next
+          end
+
+          captured = @state[via.table]
+          if captured.nil?
+            @logger.warn(
+              "  #{config.name}.reverse_scope arm '#{via.table}.#{via.column}' has no captured " \
+              "state ('#{via.table}' was not dumped before '#{config.name}'); skipping arm."
+            )
+            next
+          end
+
+          any_arm = true
+          values = captured[via.column]
+          if values.nil?
+            @logger.warn(
+              "  #{config.name}.reverse_scope arm column '#{via.table}.#{via.column}' was not " \
+              "captured while dumping '#{via.table}'; treating the arm as empty."
+            )
+            next
+          end
+
+          ids.concat(values)
+        end
+
+        return nil unless any_arm
+
+        ids = ids.flat_map { |value| value.is_a?(Array) ? value : [value] }
+        ids.compact!
+        ids.uniq!
+        { config.primary_key => { "$in" => ids } }
+      end
+
       # The set of collection names *genuinely scoped* by the dump target: the
       # target itself, plus every collection that can reach it by following
       # belongs_to edges (child -> parent) transitively. Computed by fixpoint over