exwiw 1.1.4 → 1.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edfbfddf23cb6df92da93914c6ee111a1ca7fc0085f096e82b894c8a4573b398
-  data.tar.gz: 8a96062ee9e37c1a12daec122420c1e91a06194c5f1ba1aadc3a5a5bc303a534
+  metadata.gz: 2df915162dc88ac29ccc262c436d5d7ab1797a7e026398ced3e66d1e5b73a7b7
+  data.tar.gz: 3144680abf12865a3db9d4173e4338101fa318da9f5e61e3367c5924fb24f9c6
 SHA512:
-  metadata.gz: f16c16b056138f857fcc54b1015eea30969989bb6604e5ea7fd99e2e0ab43d649a80dffc2e1887939f934ec951da28a53981a1debca854ad2bf006cf2f4cfaf3
-  data.tar.gz: e4e119962a0bc285f03e18e9540c5d7efd98b7d758240ab81f0274ee5cd44105dfeb0b15302734f5586f4e7ac4ad7933c331343090e0445aaee32c22c5e2459f
+  metadata.gz: 2726b1b47c6584d6a85ab6f1342fdfb8ac760d237c09854f81a34e36d403a3720efbe25ee47185d3f381b4384e6a3f75f47ff6002fcbaa09d4613f937b39cc1f
+  data.tar.gz: 75bb6c28ecd32adaa2aeb3488d319784811ad4ab08104560dea54982e94de51c7a7ff606b81815f6d73a41608f5f6dae49c57774a35ad837a8b6b5dab994c45d

data/AGENTS.md

@@ -0,0 +1,24 @@
+# AGENTS.md
+
+## This repository is public
+
+Everything here is world-readable: code, comments, fixtures, commit messages,
+PR and issue text, review comments, and their edit history. Deleting or editing
+text after the fact does not unpublish it.
+
+Do not include anything that comes from a private codebase:
+
+- table, column, model, or system names from a private application
+- references to private repositories or their PR / issue numbers
+- internal terminology, internal links (chat, wiki, tickets), or any customer or production data
+
+Describe motivating cases with invented, generic names, and keep planning and
+tracking in the private repository that needs the change. Re-read the title,
+body, and commit messages against this list before committing or opening a PR.
+
+## Development
+
+See [README.md](README.md) for usage and [CHANGELOG.md](CHANGELOG.md) for the
+release history. `bundle exec rake` compiles the native extension and runs the
+specs; most scripts under `e2e/` need the databases from `compose.yml`
+(the sqlite ones run without it).

data/CHANGELOG.md

@@ -2,11 +2,18 @@
 
 ## [Unreleased]
 
+## [1.1.5] - 2026-09-25
+
+### Fixed
+
+- **Single `--target-table` mode extracts every polymorphic arm, not just one.** The multi-arm union was only built in scope-column mode. In single-target mode a table reached through a polymorphic `belongs_to` followed one arm: the arm pointing at the dump target if there was one, otherwise the arm on the BFS's shortest path. Every other type's rows were dropped without a warning. Dumping `shops`, a `reviews` table with `Shop` and `Product` arms came out with the shop's own reviews but none of the reviews of its products. The arms are now resolved as in scope-column mode (an arm pointing at the dump target compares its foreign key with `--ids`, the others join or probe their target's ids) and the table is constrained to their `UNION`. One single-target rule keeps existing dumps from widening: an arm target that is constrained only by the automatic referenced-by detection does not count, because such a parent is extracted just to keep a child's foreign key valid. Dumping `products` therefore still yields only `reviewable_type = 'Product'` reviews. A declared `reverse_scope` does count. Tables that reach the target through a single arm, or through a non-polymorphic `belongs_to`, emit the same SQL as before.
+- **A table whose only route is one polymorphic arm to a table scoped by other means is no longer unscopable.** The parent cascade skipped polymorphic `belongs_to`s outright, so a table like `pictures` with a lone `imageable_type = 'Shop'` arm, pointing at a `shops` table narrowed by `reverse_scope`, was rejected in scope-column mode and dumped in full in single-target mode. The cascade now falls back to the polymorphic arms, pinned by the type column, when no plain `belongs_to` parent is scopable. A table that already had a scopable plain parent is scoped as before. A newly scoped table does, however, count as a constrained child in the automatic referenced-by detection of the tables it points at. A parent that had exactly one constrained child can now have two, so the detection steps aside and the parent falls back to the parent cascade, or is left unscopable when nothing else narrows it. Declare `reverse_scope` on the parent to keep the referencer it used before. When two independent polymorphic associations are both scopable, the table stays unscopable, and single-target mode now warns about the full dump as it does for two plain parents.
+
 ## [1.1.4] - 2026-09-18
 
 ### Fixed
 
-- **Polymorphic arms are grouped by the type column, so a config that gives each arm its own foreign key no longer loses rows.** The multi-arm walk keyed the group on `(foreign_key, foreign_type)`, which fits what the generators emit for Rails (`<name>_id` + `<name>_type`) but not a hand-written config where one type column selects between several foreign key columns — `merchant_application_type` choosing between `merchant_application_id` and `external_application_id`, say. Such arms were not recognised as siblings, so the table fell back to the single-path behavior: only the arm the BFS happened to settle on was extracted and every other arm's rows were dropped without a warning. Which arm survived depended on path length, so a table could even lose the arm it used to keep once a shorter one appeared. The group is now keyed on `foreign_type` alone and each arm joins on its own foreign key; two *independent* polymorphic associations have distinct type columns and stay in distinct groups, as before. Two consequences for such a table, both already true of the single-foreign-key case: its SQL becomes the `UNION` id-set form instead of a single JOIN, and `batch_scope` on it is now rejected in pre-flight (a batch of one terminus's ids does not constrain the other arms).
+- **Polymorphic arms are grouped by the type column, so a config that gives each arm its own foreign key no longer loses rows.** The multi-arm walk keyed the group on `(foreign_key, foreign_type)`, which fits what the generators emit for Rails (`<name>_id` + `<name>_type`) but not a hand-written config where one type column selects between several foreign key columns — `owner_type` choosing between `user_id` and `team_id`, say. Such arms were not recognised as siblings, so the table fell back to the single-path behavior: only the arm the BFS happened to settle on was extracted and every other arm's rows were dropped without a warning. Which arm survived depended on path length, so a table could even lose the arm it used to keep once a shorter one appeared. The group is now keyed on `foreign_type` alone and each arm joins on its own foreign key; two *independent* polymorphic associations have distinct type columns and stay in distinct groups, as before. Two consequences for such a table, both already true of the single-foreign-key case: its SQL becomes the `UNION` id-set form instead of a single JOIN, and `batch_scope` on it is now rejected in pre-flight (a batch of one terminus's ids does not constrain the other arms).
 
 ## [1.1.3] - 2026-09-08
 

data/README.md

@@ -153,8 +153,8 @@ Only the dump target itself is filtered by `--ids` directly. Every *other* table
 How the paths behave and interact:
 
 1. **Direct filter.** In the default single-target mode the target is anchored on its primary key (or a custom field via the mongodb-only `--ids-field`). In [scope-column mode](#scope-column-mode) there is no single anchor: every table that declares a `scope_column` is filtered on that column directly.
-2. **`belongs_to` join walk** — the "normal join" path. exwiw BFS-walks `belongs_to` edges to the nearest terminus (the target table, or a directly scoped table in scope-column mode) and compiles the shortest path into `INNER JOIN`s. A [polymorphic `belongs_to`](#polymorphic-belongs_to) hop additionally pins the type column; in scope-column mode a polymorphic hop is resolved for **every** concrete arm and the arms are `UNION`ed (see [Every arm is extracted](#every-arm-is-extracted-scope-column-mode)).
-3. **Referenced-by** handles a table with no outgoing path that is pointed *at* by a constrained child — `active_storage_blobs`, referenced by `active_storage_attachments.blob_id`, is the canonical case (see [ActiveStorage](#activestorage-has_one_attached--has_many_attached)). It is automatic but deliberately narrow: it requires a single, non-polymorphic referencer. With two or more referencers it steps aside (path 6) unless you declare `reverse_scope`.
+2. **`belongs_to` join walk** — the "normal join" path. exwiw BFS-walks `belongs_to` edges to the nearest terminus (the target table, or a directly scoped table in scope-column mode) and compiles the shortest path into `INNER JOIN`s. A [polymorphic `belongs_to`](#polymorphic-belongs_to) hop additionally pins the type column, and is resolved for **every** concrete arm with the arms `UNION`ed (see [Every arm is extracted](#every-arm-is-extracted)).
+3. **Referenced-by** handles a table with no outgoing path that is pointed *at* by a constrained child — `active_storage_blobs`, referenced by `active_storage_attachments.blob_id`, is the canonical case (see [ActiveStorage](#activestorage-has_one_attached--has_many_attached)). It is automatic but deliberately narrow: it requires a single, non-polymorphic referencer. With two or more referencers it steps aside to path 5, then 6, unless you declare `reverse_scope`.
 4. **[`reverse_scope`](#reverse-scope-for-multi-referencer-tables-reverse_scope)** is the declared, multi-referencer form of path 3: the config enumerates which referencers' (already scoped) queries feed the id set. Unscoped arms are skipped with a warning rather than widening the dump.
 5. **Scoped-parent cascade** rescues satellites: a table whose only link is a `belongs_to` toward a hub that is itself scoped (e.g. via referenced-by or `reverse_scope`) is constrained to that parent's in-scope ids. The cascade recurses hop by hop (each level requires a single unambiguous scopable parent) and stops on `belongs_to` cycles.
 6. **Full dump** is the fallback for a genuinely unrelated table — intended for reference/master data. Single-target mode dumps it in full (with a warning when an ambiguous cascade was the reason); scope-column mode refuses to run instead, unless the table is explicitly marked [`scope_exempt: true`](#scope_exempt-intentional-full-dump) (Rails-managed tables are exempt automatically).
@@ -783,9 +783,9 @@ WHERE reviews.reviewable_id IN (/* products subquery */)
 
 The same type filter is applied on the join path when the polymorphic table is an intermediate hop rather than the directly-dumped table.
 
-#### Every arm is extracted (scope-column mode)
+#### Every arm is extracted
 
-A polymorphic `belongs_to` is several `belongs_to` entries — one per concrete target — that a row selects between via its type column. A single JOIN can only follow **one** of them, so a join table reached through such a hop would come out holding only the rows of that one `type_value`. In [scope-column mode](#scope-column-mode) exwiw therefore resolves **every** arm of the group and constrains the table to the union of the ids the arms keep:
+A polymorphic `belongs_to` is several `belongs_to` entries — one per concrete target — that a row selects between via its type column. A single JOIN can only follow **one** of them, so a join table reached through such a hop would come out holding only the rows of that one `type_value`. exwiw therefore resolves **every** arm of the group and constrains the table to the union of the ids the arms keep. In [scope-column mode](#scope-column-mode):
 
 ```sql
 SELECT comments.* FROM comments
@@ -811,15 +811,35 @@ Notes:
 - **Only arms that reach the scope are included.** An arm whose target has no scope of its own is dropped, never widened — an unscoped arm would pull in every tenant's rows. An arm marked `"ignore": true` is dropped as usual, before any of this.
 - An arm's target does not need a `belongs_to` path to a scoped table: if it is scoped by other means (referenced-by, [`reverse_scope`](#reverse-scope-for-multi-referencer-tables-reverse_scope), or the parent cascade) the arm probes that query's ids instead, still pinned by the type column.
 - An arm whose target is scoped **through this same table** (e.g. `active_storage_blobs`, narrowed by referenced-by from `active_storage_attachments`, appearing as an `ActiveStorage::Blob` arm of those same attachments) is dropped: adopting it would make the two tables scope each other and leave the referenced table short of rows the join table kept — a dangling foreign key on import.
-- **Arms are grouped by the type column (`foreign_type`), not by the foreign key.** Rails keeps every arm's id in one `<name>_id` column, which is what the generators emit, but a hand-written config may give each arm its own foreign key while one type column still selects between them — e.g. `merchant_application_type` choosing between `merchant_application_id` and `external_application_id`. Those are arms of the same discriminator, so each is resolved and joined on its own key. Two *independent* polymorphic associations on one table have distinct type columns and therefore stay in distinct groups.
-- Nothing changes when there is a single arm, or when the walk leaves through a non-polymorphic `belongs_to`: the plain single-JOIN SQL is emitted, byte for byte as before.
-- This applies to the scope-column mode walk. The single `--target-table` mode still follows one path per table.
+- **Arms are grouped by the type column (`foreign_type`), not by the foreign key.** Rails keeps every arm's id in one `<name>_id` column, which is what the generators emit, but a hand-written config may give each arm its own foreign key while one type column still selects between them — e.g. `owner_type` choosing between `user_id` and `team_id`. Those are arms of the same discriminator, so each is resolved and joined on its own key. Two *independent* polymorphic associations on one table have distinct type columns and therefore stay in distinct groups.
+- **The route the walk picks decides whether the arms are unioned.** The route is the shortest one; in single-target mode a `belongs_to` pointing at the dump target itself is taken first. When the route leaves through a polymorphic arm, every arm of that type column is unioned. When it leaves through a non-polymorphic `belongs_to`, the table is joined along that route alone and the polymorphic arms are not unioned in, so a row reachable only through an arm is not extracted. A plain `belongs_to` is not preferred over a shorter polymorphic route. A single arm is emitted as a plain JOIN.
+- A table with no route of its own falls back to the parent cascade, which does prefer plain parents. A scopable plain parent is used when there is exactly one. Only when there is none are the polymorphic `belongs_to`s consulted: the arms of one type column that point at tables scoped by other means (referenced-by, `reverse_scope`, or the cascade) are unioned, each pinned by the type column. Multiple independent polymorphic associations that are all scopable are as ambiguous as multiple plain parents, so the table is left unscopable (dumped in full with a warning in single-target mode). A table scoped this way also counts as a constrained child in the [referenced-by](#how-each-table-is-narrowed--the-six-scoping-paths) detection of the tables it points at, so a parent that had a single constrained referencer may now have two and be narrowed by the next path instead.
+
+In single `--target-table` mode the same union is built. An arm that points at the dump target itself compares its foreign key with `--ids`, and the other arms join or probe their way to the target as above. One difference: an arm target that is constrained **only** by the automatic referenced-by detection does not count. Such a parent is extracted just to keep a child's foreign key valid; it does not own the rows that point at it. So dumping `products` still pulls only `reviewable_type = 'Product'` reviews, even though the product's shop is extracted too, while dumping `shops` pulls the shop's own reviews **and** the reviews of its products:
+
+```sql
+SELECT reviews.* FROM reviews
+JOIN (
+  SELECT DISTINCT exwiw_scope_src_0.id AS exwiw_scope_id
+  FROM (
+    SELECT reviews.id FROM reviews
+      JOIN products ON reviews.reviewable_id = products.id
+        AND products.shop_id = 1 AND reviews.reviewable_type = 'Product'
+    UNION
+    SELECT reviews.id FROM reviews
+    WHERE reviews.reviewable_id = 1 AND reviews.reviewable_type = 'Shop'
+  ) AS exwiw_scope_src_0
+) AS exwiw_scope_ids_0
+  ON reviews.id = exwiw_scope_ids_0.exwiw_scope_id
+```
+
+A declared [`reverse_scope`](#reverse-scope-for-multi-referencer-tables-reverse_scope) does count, since declaring it states that the referencers own the rows.
 
 ### ActiveStorage (`has_one_attached` / `has_many_attached`)
 
 ActiveStorage is handled automatically — no ActiveStorage-specific configuration is required. The `has_one_attached` / `has_many_attached` macros don't add a column to the owning model; they generate ordinary associations that exwiw already understands:
 
-- **`active_storage_attachments`** is the polymorphic join row (`belongs_to :record, polymorphic: true` + `belongs_to :blob`). `exwiw:schema:generate` expands the polymorphic `record` into one `belongs_to` per model that declared `has_*_attached` (found via the generated `has_* ..., as: :record` reflections), exactly like any other [polymorphic `belongs_to`](#polymorphic-belongs_to). So only the attachments whose owner is among the dumped rows are extracted. In scope-column mode every owner type that reaches the scope is extracted (see [Every arm is extracted](#every-arm-is-extracted-scope-column-mode)); before that, only the single owner type the walk happened to settle on came out.
+- **`active_storage_attachments`** is the polymorphic join row (`belongs_to :record, polymorphic: true` + `belongs_to :blob`). `exwiw:schema:generate` expands the polymorphic `record` into one `belongs_to` per model that declared `has_*_attached` (found via the generated `has_* ..., as: :record` reflections), exactly like any other [polymorphic `belongs_to`](#polymorphic-belongs_to). So only the attachments whose owner is among the dumped rows are extracted. Every owner type that reaches the scope is extracted (see [Every arm is extracted](#every-arm-is-extracted)); before that, only the single owner type the walk happened to settle on came out.
 - **`active_storage_blobs`** has no `belongs_to` of its own (attachments point *at* it), so it has no path to the dump target. exwiw narrows it via **reverse / "referenced_by" extraction**: a parent table referenced by exactly one constrained, non-polymorphic child is constrained to just the referenced ids instead of dumping every row. The id set is materialized once and joined back (see [Why a JOIN, not `IN (subquery)`](#why-a-join-not-in-subquery)):
 
   ```sql

data/lib/exwiw/query_ast_builder.rb

@@ -72,6 +72,8 @@ module Exwiw
     # automatic reverse detection step aside, when it did.
     attr_reader :ambiguous_referencers
 
+    attr_reader :narrowed_by_automatic_reverse
+
     def initialize(table_name, table_by_name, dump_target, logger, allow_reverse: true, allow_declared_reverse: true, forward_path: [], reverse_path: [], deep_chain_warned: nil, batch_ids: nil)
       @table_name = table_name
       @table_by_name = table_by_name
@@ -103,6 +105,7 @@ module Exwiw
       # Deep-chain warnings already emitted, keyed by chain path and shared (the
       # same Hash) across every recursive build under one top-level run.
       @deep_chain_warned = deep_chain_warned || {}
+      @narrowed_by_automatic_reverse = false
     end
 
     def run
@@ -110,8 +113,15 @@ module Exwiw
 
       return build_scoped(table) if scope_mode?
 
-      where_clauses = build_where_clauses(table, dump_target)
-      join_clauses = build_join_clauses(table, table_by_name, dump_target)
+      arm_queries = target_polymorphic_arm_queries(table)
+      if arm_queries
+        where_clauses = [pk_union_clause(table, arm_queries)]
+        where_clauses.push(table.filter) if table.filter
+        join_clauses = []
+      else
+        where_clauses = build_where_clauses(table, dump_target)
+        join_clauses = build_join_clauses(table, table_by_name, dump_target)
+      end
 
       # Reverse / "referenced_by" extraction. A table with no belongs_to path to
       # the dump target produces no where/join clauses and would otherwise dump
@@ -126,7 +136,10 @@ module Exwiw
          table.name != dump_target.table_name &&
          where_clauses.empty? && join_clauses.empty?
         reverse_clause = build_referenced_by_clause(table)
-        where_clauses.push(reverse_clause) if reverse_clause
+        if reverse_clause
+          where_clauses.push(reverse_clause)
+          @narrowed_by_automatic_reverse = !explicit_reverse_scope?(table)
+        end
       end
 
       # Forward cascade. A satellite of a reverse_scope'd (or referenced-by-scoped)
@@ -141,7 +154,7 @@ module Exwiw
         if parent_clause
           where_clauses.push(parent_clause)
         elsif @allow_reverse && @forward_path.empty? && !scope_exempt?(table) &&
-              scopable_parent_candidates(table).size > 1
+              (scopable_parent_candidates(table).size > 1 || polymorphic_parent_groups(table).size > 1)
           @logger.warn(
             "  #{table.name} belongs_to multiple scopable parents; the cascade cannot " \
             "pick one unambiguously, so it is dumped in full. If this is intended, set " \
@@ -184,63 +197,60 @@ module Exwiw
       # the path is 1, it's impossible case
       return [] if path_tables.size < 2
 
-      join_clauses = []
-
-      path_tables.each_cons(2) do |from_table_name, to_table_name|
+      path_tables.each_cons(2).map do |from_table_name, to_table_name|
         from_table = table_by_name[from_table_name]
         to_table = table_by_name[to_table_name]
+        build_join_clause(from_table, to_table, from_table.belongs_to(to_table_name))
+      end
+    end
 
-        relation = from_table.belongs_to(to_table_name)
+    private def build_join_clause(from_table, to_table, relation)
+      join_clause = QueryAst::JoinClause.new(
+        base_table_name: from_table.name,
+        foreign_key: relation.foreign_key,
+        join_table_name: to_table.name,
+        primary_key: to_table.primary_key,
+        where_clauses: [],
+        base_where_clauses: []
+      )
 
-        join_clause = QueryAst::JoinClause.new(
-          base_table_name: from_table.name,
-          foreign_key: relation.foreign_key,
-          join_table_name: to_table.name,
-          primary_key: to_table.primary_key,
-          where_clauses: [],
-          base_where_clauses: []
+      # When this hop itself is a polymorphic belongs_to (e.g. comments
+      # polymorphically belongs_to posts as commentable), the type column
+      # (foreign_type) lives on the source table (from_table = base_table_name).
+      # The foreign key alone is not enough — a value like reviewable_id=1 can
+      # collide with rows of another model — so add the type condition to
+      # base_where_clauses to narrow down the source table.
+      if relation.polymorphic?
+        join_clause.base_where_clauses.push QueryAst::WhereClause.new(
+          column_name: relation.foreign_type,
+          operator: :eq,
+          value: [relation.type_value]
         )
-
-        # When this hop itself is a polymorphic belongs_to (e.g. comments
-        # polymorphically belongs_to posts as commentable), the type column
-        # (foreign_type) lives on the source table (from_table = base_table_name).
-        # The foreign key alone is not enough — a value like reviewable_id=1 can
-        # collide with rows of another model — so add the type condition to
-        # base_where_clauses to narrow down the source table.
-        if relation.polymorphic?
-          join_clause.base_where_clauses.push QueryAst::WhereClause.new(
-            column_name: relation.foreign_type,
+      end
+      relation_to_dump_target = to_table.belongs_to(dump_target.table_name)
+      if relation_to_dump_target
+        join_clause.where_clauses.push dump_target_fk_clause(relation_to_dump_target.foreign_key)
+
+        # When the intermediate table polymorphically belongs_to the dump
+        # target, also add the type column (foreign_type) to the join
+        # condition. The type column lives on to_table (= join_table_name), so
+        # it rides on the existing mechanism where a JoinClause's where_clauses
+        # are compiled against join_table_name.
+        if relation_to_dump_target.polymorphic?
+          join_clause.where_clauses.push QueryAst::WhereClause.new(
+            column_name: relation_to_dump_target.foreign_type,
             operator: :eq,
-            value: [relation.type_value]
+            value: [relation_to_dump_target.type_value]
           )
         end
-        relation_to_dump_target = to_table.belongs_to(dump_target.table_name)
-        if relation_to_dump_target
-          join_clause.where_clauses.push dump_target_fk_clause(relation_to_dump_target.foreign_key)
-
-          # When the intermediate table polymorphically belongs_to the dump
-          # target, also add the type column (foreign_type) to the join
-          # condition. The type column lives on to_table (= join_table_name), so
-          # it rides on the existing mechanism where a JoinClause's where_clauses
-          # are compiled against join_table_name.
-          if relation_to_dump_target.polymorphic?
-            join_clause.where_clauses.push QueryAst::WhereClause.new(
-              column_name: relation_to_dump_target.foreign_type,
-              operator: :eq,
-              value: [relation_to_dump_target.type_value]
-            )
-          end
-        end
-
-        # Add filter from intermediate table to join clause
-        if to_table.filter
-          join_clause.where_clauses.push to_table.filter
-        end
+      end
 
-        join_clauses.push(join_clause)
+      # Add filter from intermediate table to join clause
+      if to_table.filter
+        join_clause.where_clauses.push to_table.filter
       end
 
-      join_clauses
+      join_clause
     end
 
     # Builds a `pk IN (SELECT child.fk FROM <child extraction query>)` clause
@@ -419,6 +429,14 @@ module Exwiw
     private def build_belongs_to_scoped_clause(table)
       candidates = scopable_parent_candidates(table)
 
+      # Plain parents take precedence over polymorphic ones: polymorphic parents
+      # are consulted only when no plain parent is scopable. Multiple independent
+      # polymorphic associations are as ambiguous as multiple plain parents.
+      if candidates.empty?
+        groups = polymorphic_parent_groups(table)
+        return groups.size == 1 ? pk_union_clause(table, groups.first) : nil
+      end
+
       # Only the unambiguous single-parent case. Multiple scopable parents would
       # need their subqueries combined (not supported); fall back to unscopable.
       if candidates.size != 1
@@ -446,6 +464,21 @@ module Exwiw
       )
     end
 
+    private def polymorphic_parent_groups(table)
+      @polymorphic_parent_groups ||= {}
+      return @polymorphic_parent_groups[table.name] if @polymorphic_parent_groups.key?(table.name)
+
+      @polymorphic_parent_groups[table.name] =
+        if table.primary_key.nil?
+          []
+        else
+          table.belongs_tos.select(&:polymorphic?).group_by(&:foreign_type).filter_map do |_, relations|
+            arm_queries = relations.filter_map { |relation| scoped_target_arm_query(table, relation) }
+            arm_queries unless arm_queries.empty?
+          end
+        end
+    end
+
     # The scopable belongs_to parents of `table`: each non-polymorphic parent
     # whose own extraction query comes out constrained, paired with the relation
     # and that query. Shared by build_belongs_to_scoped_clause (which requires
@@ -556,6 +589,53 @@ module Exwiw
       )
     end
 
+    # Single-target counterpart of #scoped_arms.
+    private def target_polymorphic_arm_queries(table)
+      return nil if table.name == dump_target.table_name
+
+      first_hop =
+        if table.belongs_to(dump_target.table_name)
+          dump_target.table_name
+        else
+          find_path_to_dump_target(table, table_by_name, dump_target)[1]
+        end
+      return nil if first_hop.nil?
+
+      sibling_arms = polymorphic_sibling_arms(table, first_hop)
+      return nil if sibling_arms.nil?
+
+      arm_queries = sibling_arms.filter_map { |relation| target_arm_query(table, relation) }
+      @logger.debug(
+        "  #{table.name} reaches the dump target through #{arm_queries.size} of " \
+        "#{sibling_arms.size} polymorphic '#{sibling_arms.first.foreign_type}' arm(s)."
+      )
+      # A lone arm is always the one the shortest path leaves through, which the
+      # single-path build already emits as a plain JOIN.
+      arm_queries.size >= 2 ? arm_queries : nil
+    end
+
+    private def target_arm_query(table, relation)
+      if relation.table_name == dump_target.table_name
+        return arm_pk_query(table).tap do |query|
+          query.where dump_target_fk_clause(relation.foreign_key)
+          query.where polymorphic_type_clause(relation)
+        end
+      end
+
+      target = table_by_name[relation.table_name]
+      return nil if target.nil?
+
+      path = find_path_to_dump_target(target, table_by_name, dump_target)
+      if path.any? && !path.include?(table.name)
+        return arm_pk_query(table).tap do |query|
+          query.join(build_join_clause(table, target, relation))
+          build_join_clauses(target, table_by_name, dump_target).each { |join_clause| query.join(join_clause) }
+        end
+      end
+
+      scoped_target_arm_query(table, relation)
+    end
+
     private def find_path_to_dump_target(table, table_by_name, dump_target)
       return [] if table.name == dump_target.table_name
 
@@ -935,15 +1015,33 @@ module Exwiw
       path = find_path_to_scoped(table, first_relation: relation)
       return ScopedArm.new(relation: relation, path: path) if path.size >= 2
 
+      target_query = scoped_target_query(table, relation, allow_automatic_reverse: true)
+      target_query && ScopedArm.new(relation: relation, target_query: target_query)
+    end
+
+    private def scoped_target_arm_query(table, relation)
+      # A parent kept only by the automatic referenced_by exists to keep a child's
+      # foreign key valid. Single-target mode extracts only what sits under the
+      # dump target, so such a parent must not pull in the rows that point at it.
+      target_query = scoped_target_query(table, relation, allow_automatic_reverse: scope_mode?)
+      target_query && target_ids_arm_query(table, relation, target_query)
+    end
+
+    private def scoped_target_query(table, relation, allow_automatic_reverse:)
       target = table_by_name[relation.table_name]
       return nil if target.nil? || target.primary_key.nil?
       # Descending into a table already being resolved would close a cycle.
       return nil if target.name == table.name || @forward_path.include?(target.name)
 
-      target_query = self.class.run(
+      # Built the same way as the target's own extraction, so the arm never keeps
+      # a row pointing at a target row the dump leaves out.
+      builder = self.class.new(
         target.name, table_by_name, dump_target, @logger,
-        allow_reverse: true, forward_path: @forward_path + [table.name], reverse_path: @reverse_path, deep_chain_warned: @deep_chain_warned
+        forward_path: @forward_path + [table.name], reverse_path: @reverse_path, deep_chain_warned: @deep_chain_warned
       )
+      target_query = builder.run
+      return nil if !allow_automatic_reverse && builder.narrowed_by_automatic_reverse
+
       # An unconstrained target selects every id, i.e. does not scope the arm at
       # all; dropping the arm is the safe outcome.
       return nil unless target_query.where_clauses.any? || target_query.join_clauses.any?
@@ -964,7 +1062,7 @@ module Exwiw
         return nil
       end
 
-      ScopedArm.new(relation: relation, target_query: target_query)
+      target_query
     end
 
     # The polymorphic belongs_to arms sharing the `foreign_type` of the relation
@@ -1019,42 +1117,57 @@ module Exwiw
     # (`replace_with` / `raw_sql`) configured on it cannot corrupt the id
     # comparison — the same guard the reverse-scope projections use.
     private def polymorphic_arms_clause(table, arms)
-      pk_column = TableColumn.from_symbol_keys(name: table.primary_key)
-
       queries = arms.map do |arm|
-        query = QueryAst::Select.new
-        query.from(table.name)
-        query.select([pk_column])
-
         if arm.path
-          build_scoped_join_clauses(arm.path, first_relation: arm.relation).each { |jc| query.join(jc) }
+          arm_pk_query(table).tap do |query|
+            build_scoped_join_clauses(arm.path, first_relation: arm.relation).each { |jc| query.join(jc) }
+          end
         else
-          # The arm's target is scoped without a join path of its own, so probe
-          # its id set instead of joining up to a scoped ancestor. The type
-          # column still has to be constrained: the foreign key alone cannot tell
-          # this arm's rows from another arm's (record_id=1 may be any type).
-          target = table_by_name.fetch(arm.relation.table_name)
-          query.where QueryAst::WhereClause.new(
-            column_name: arm.relation.foreign_key,
-            operator: :in_subquery,
-            value: QueryAst::SelectSubquery.new(
-              query: project_query_to(arm.target_query, target.primary_key)
-            )
-          )
-          query.where QueryAst::WhereClause.new(
-            column_name: arm.relation.foreign_type,
-            operator: :eq,
-            value: [arm.relation.type_value]
-          )
+          target_ids_arm_query(table, arm.relation, arm.target_query)
         end
-
-        query
       end
 
+      pk_union_clause(table, queries)
+    end
+
+    private def pk_union_clause(table, arm_queries)
       QueryAst::WhereClause.new(
         column_name: table.primary_key,
         operator: :in_subquery,
-        value: QueryAst::UnionSubquery.new(queries: queries)
+        value: QueryAst::UnionSubquery.new(queries: arm_queries)
+      )
+    end
+
+    private def arm_pk_query(table)
+      QueryAst::Select.new.tap do |query|
+        query.from(table.name)
+        query.select([TableColumn.from_symbol_keys(name: table.primary_key)])
+      end
+    end
+
+    # The arm's target is scoped without a join path of its own, so probe its id
+    # set instead of joining up to a scoped ancestor. The type column still has
+    # to be constrained: the foreign key alone cannot tell this arm's rows from
+    # another arm's (record_id=1 may be any type).
+    private def target_ids_arm_query(table, relation, target_query)
+      target = table_by_name.fetch(relation.table_name)
+      arm_pk_query(table).tap do |query|
+        query.where QueryAst::WhereClause.new(
+          column_name: relation.foreign_key,
+          operator: :in_subquery,
+          value: QueryAst::SelectSubquery.new(
+            query: project_query_to(target_query, target.primary_key)
+          )
+        )
+        query.where polymorphic_type_clause(relation)
+      end
+    end
+
+    private def polymorphic_type_clause(relation)
+      QueryAst::WhereClause.new(
+        column_name: relation.foreign_type,
+        operator: :eq,
+        value: [relation.type_value]
       )
     end
 

data/lib/exwiw/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Exwiw
-  VERSION = "1.1.4"
+  VERSION = "1.1.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exwiw
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.1.5
 platform: ruby
 authors:
 - Shia
@@ -47,6 +47,7 @@ extensions:
 - ext/exwiw/ext_json/extconf.rb
 extra_rdoc_files: []
 files:
+- AGENTS.md
 - CHANGELOG.md
 - LICENSE.txt
 - README.md