exwiw 0.8.1 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80610cc2d13a87793171563b2b8e4ff0568135eb987b550dd9f89bffe89b1d67
-  data.tar.gz: 5e9f4976043571647163e9f743c3c8fb709a29944b590c55424dce374cca3269
+  metadata.gz: 90d949cb54565ed644b599102cfabc16236fe2d83523594cd7b14f269118a9b2
+  data.tar.gz: 7236bb6ee6b9dda38aec93491f0266e334890e3c271b4f7d5d072d46a1e0f88b
 SHA512:
-  metadata.gz: 8508aaa2d9cba3310a9ee4d4b940682b894bbafcab9672e4ccca5fb8f1a4b43e6fe9c36cbfcd0efe8f12c5308fa9be33aeb16d53b6d98ef71692ec2e30076be0
-  data.tar.gz: 8a1a8187e7547f4ce0eeaee458d36b16e56c08c1f2275977127de56a49eb2a3b25e22d8c52d3678fa6ea91e553ebf6c69bf943e5bb108e3984fa8fc34f03a2f0
+  metadata.gz: bcfac0aaf220b55dfa3172f94d2ad0a6e828f53253e367aa9203db7061695fa6a9188e22a92c18d51bd9a55b6a9bf840cf780a3647d4aca2a0cccff1a785a347
+  data.tar.gz: d891fc7101fea30d674b933213715a8a4534c459e191b9bf4fce31b3bda8a9be037bf09627419f43ef914d2a9288aa40e1cd4836a4d8e1e0901d73e320218cd3

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.8.3] - 2026-06-24
+
+### Fixed
+
+- **Forward scope (`via_scoped_parent`) now cascades across multiple `belongs_to` hops instead of dying after one.** A table with no scope column of its own is scoped by constraining it to its `belongs_to` parent's in-scope ids (`fk IN (SELECT parent.pk FROM <parent's scoped query>)`). Previously the parent was rebuilt with forward scoping turned off, so if the parent was *itself* scoped only through *its* parent (e.g. an identity-family table two or more hops below a `reverse_scope`/`referenced_by` table — `users ← end_users ← end_user_profiles`), the rebuilt parent came back unconstrained and the child was classified `:unscopable` — forcing a `scope_exempt` full dump and re-introducing the bloat the prune removes. The boolean single-hop bound is replaced by a forward-path guard: the rescue keeps forward scoping enabled while rebuilding the parent (appending the current table to the path), so the cascade recurses N levels and produces a correspondingly nested `IN (subquery)`; it terminates only on a genuine `belongs_to` cycle (a table already on the path is not revisited, falling through to `:unscopable`). The single-unambiguous-parent rule and the polymorphic-skip are unchanged, and the reverse arms still cannot loop back through the table being reverse-scoped. SQL adapters only.
+
+## [0.8.2] - 2026-06-24
+
+### Added
+
+- **Multi-referencer reverse scoping (`reverse_scope`).** Reverse / "referenced_by" extraction previously narrowed only a table referenced by *exactly one* constrained child; a table referenced by two or more (most importantly a **global-identity table** like `users`, which carries no scope/tenant column and has no `belongs_to` of its own, yet many scoped tables point *at* it) fell back to dumping every row — dragging in every tenant's identities. A table can now opt into **multi-referencer** reverse scoping with a user-owned `reverse_scope: { via: [{ table, column }, …] }` key listing the referencers whose own (already scoped) extraction queries are `UNION`'d into the id set it is constrained to (`pk IN (SELECT ref1.col1 FROM ref1 <scope> UNION SELECT ref2.col2 FROM ref2 <scope> …)`). Each arm reuses that referencer's own scope, so a per-tenant run keeps only that tenant's ids; the named `column` is explicit, so a non-default foreign key (or a column with no declared `belongs_to`) is honored; NULLs are excluded per arm. Only **scoped** referencers belong in `via` — an unconstrained arm (e.g. a `scope_exempt` referencer) would union every row back, so it is skipped with a warning rather than silently widening the dump, and an unknown table is likewise skipped; if no arm survives, the table stays unscopable (so scope-column mode's `validate_scope!` still aborts rather than dumping it in full). Tables that `belongs_to` the reverse-scoped table tighten automatically through the existing cascade and need no config. `reverse_scope` is never emitted by `schema:generate` and is preserved across regeneration like `scope_exempt`/`scope_column`. SQL adapters only. See the [README](README.md#reverse-scope-for-multi-referencer-tables-reverse_scope).
+
 ## [0.8.1] - 2026-06-24
 
 ### Fixed

data/README.md

@@ -183,8 +183,11 @@ Each table is resolved as follows:
   (`fk IN (SELECT parent.pk FROM <parent's scoped query>)`). This covers a *hub*
   table that has no scope column and is scoped only because an extractable child
   references it (see referenced-by below): the hub's other `belongs_to` children
-  ride along to just the in-scope rows instead of being dumped in full. Limited to
-  a single forward hop and a single unambiguous scopable parent.
+  ride along to just the in-scope rows instead of being dumped in full. The parent
+  itself may be scoped the same way, so this **cascades across multiple hops**
+  (each a single unambiguous scopable parent) and the subquery nests
+  correspondingly; the recursion terminates on a genuine `belongs_to` cycle (a
+  table already on the path is left `:unscopable` rather than looped on).
 - **Cannot be scoped at all** (no scope column and no path to one) → exwiw
   **aborts** and lists the offending tables, so an unscoped table is never silently
   dumped in full. For each, either declare a `scope_column`, add a `belongs_to`
@@ -579,6 +582,49 @@ ActiveStorage is handled automatically — no ActiveStorage-specific configurati
   `active_storage_variant_records` also references blobs, but since it has no path of its own to the dump target it doesn't constrain anything and is ignored as a referencer — blobs stays narrowed to the attachment-referenced ids. (A parent referenced by *multiple* constrained children currently falls back to dumping all of its rows.)
 - **`active_storage_variant_records`** holds derivative variant-tracking rows that ActiveStorage regenerates lazily, and it too has no path to the dump target — left alone it would land in the "no relation → dump all" branch and, worse, its `blob_id` could point at blobs outside the narrowed set above (a foreign-key violation on import). `exwiw:schema:generate` therefore emits it with **`ignore: true`** (and drops it from the attachments `record` polymorphic expansion so nothing carries a dangling reference to it), so its data is skipped while the DDL is still written. Remove `ignore` from the generated config if you really need to export it.
 
+### Reverse scope for multi-referencer tables (`reverse_scope`)
+
+The automatic reverse extraction above narrows a table referenced by **exactly one** constrained child. A table referenced by **two or more** constrained children falls back to dumping every row — fine for `active_storage_blobs`, but a problem for a **global-identity table** such as `users`: it carries no scope/tenant column and has no `belongs_to` of its own, yet dozens of scoped tables point *at* it. Dumping it (and everything that hangs off it) in full pulls in every tenant's identities.
+
+`reverse_scope` opts such a table into **multi-referencer** reverse scoping: you enumerate the referencers whose own (already scoped) extraction queries should be `UNION`'d into the id set the table is constrained to. It is a user-owned key (never emitted by `schema:generate`, preserved across regeneration like `scope_exempt`/`scope_column`):
+
+```json
+{
+  "name": "users",
+  "primary_key": "id",
+  "reverse_scope": {
+    "via": [
+      { "table": "customers", "column": "user_id" },
+      { "table": "staff", "column": "user_id" },
+      { "table": "business_entity_customers", "column": "kantan_yoyaku_user_id" }
+    ]
+  },
+  "columns": [{ "name": "id" }, { "name": "name" }]
+}
+```
+
+produces (each arm reuses that referencer's own scope, so a per-tenant run keeps only that tenant's ids):
+
+```sql
+SELECT users.* FROM users
+WHERE users.id IN (
+  SELECT customers.user_id FROM customers WHERE <customers' scope> AND customers.user_id IS NOT NULL
+  UNION
+  SELECT staff.user_id FROM staff WHERE <staff' scope> AND staff.user_id IS NOT NULL
+  UNION
+  SELECT business_entity_customers.kantan_yoyaku_user_id FROM business_entity_customers
+    WHERE <…' scope> AND business_entity_customers.kantan_yoyaku_user_id IS NOT NULL
+)
+```
+
+Notes:
+
+- **`column` is explicit**, so a *non-default* foreign key (e.g. `kantan_yoyaku_user_id`, or `organization_admins.id` which itself references `users.id`) is honored, and even a column with no declared `belongs_to` edge can be enumerated.
+- **Only scoped referencers belong in `via`.** Each arm's query must come out constrained; an unconstrained referencer (e.g. a `scope_exempt` table, or one with no path to a scope) would project *every* id and union the whole table back — so such an arm is **skipped with a warning** rather than silently widening the dump. An unknown table is likewise skipped with a warning. If no arm survives, the table stays unscopable and (in [scope-column mode](#scope-column-mode)) the run aborts via `validate_scope!`.
+- **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. Polymorphic foreign keys are not eligible as anchors (the named `column` is always a concrete column).
+
 ### Rails-managed tables (special `type` values)
 
 Some tables are owned by Rails itself rather than the application — they have no ActiveRecord model and Rails reserves the right to evolve their column shape between versions (e.g. `schema_migrations`, `ar_internal_metadata`). exwiw treats them as a distinct category via the `type` field on a table config:

data/lib/exwiw/adapter/mysql_adapter.rb

@@ -280,6 +280,8 @@ module Exwiw
           end
         elsif where_clause.operator == :in_subquery
           "#{key} IN (#{compile_subquery(where_clause.value)})"
+        elsif where_clause.operator == :not_null
+          "#{key} IS NOT NULL"
         else
           raise "Unsupported operator: #{where_clause.operator}"
         end
@@ -290,6 +292,12 @@ module Exwiw
         # extraction query, projected to a foreign key); compile it as-is.
         return compile_ast(subquery.query) if subquery.is_a?(Exwiw::QueryAst::SelectSubquery)
 
+        # A UnionSubquery wraps several such Selects; UNION their compiled forms
+        # into a single id set.
+        if subquery.is_a?(Exwiw::QueryAst::UnionSubquery)
+          return subquery.queries.map { |q| compile_ast(q) }.join(' UNION ')
+        end
+
         inner_values = subquery.where_values.map { |v| escape_value(v) }
         "SELECT #{subquery.table_name}.#{subquery.select_column} " \
           "FROM #{subquery.table_name} " \

data/lib/exwiw/adapter/postgresql_adapter.rb

@@ -364,6 +364,8 @@ module Exwiw
           cast_to = subquery_cast_to(where_clause.value, table_name, where_clause.column_name)
           outer_key = cast_to ? "#{key}::#{cast_to}" : key
           "#{outer_key} IN (#{subquery_sql})"
+        elsif where_clause.operator == :not_null
+          "#{key} IS NOT NULL"
         else
           raise "Unsupported operator: #{where_clause.operator}"
         end
@@ -376,6 +378,15 @@ module Exwiw
           return compile_ast(subquery.query, select_cast_to: cast_to)
         end
 
+        # A UnionSubquery wraps several projected Selects; UNION their compiled
+        # forms. cast_to is the union-wide decision (see union_cast_to): when any
+        # arm's column type would clash with the outer column or another arm,
+        # every arm's projected column and the outer key are cast to text so the
+        # UNION and the enclosing IN comparison resolve to one type.
+        if subquery.is_a?(Exwiw::QueryAst::UnionSubquery)
+          return subquery.queries.map { |q| compile_ast(q, select_cast_to: cast_to) }.join(' UNION ')
+        end
+
         inner_values = subquery.where_values.map { |v| escape_value(v) }
         select_expr = "#{subquery.table_name}.#{subquery.select_column}"
         select_expr = "#{select_expr}::#{cast_to}" if cast_to
@@ -400,6 +411,11 @@ module Exwiw
       private def subquery_cast_to(subquery, outer_table, outer_column)
         return nil if outer_table.nil? || outer_column.nil?
 
+        # A UNION's arms (and the enclosing IN comparison) must all resolve to
+        # one type, so the cast decision must weigh every arm — not just one, as
+        # a flat Subquery would.
+        return union_cast_to(subquery, outer_table, outer_column) if subquery.is_a?(Exwiw::QueryAst::UnionSubquery)
+
         inner_table, inner_column = subquery_select_target(subquery)
         return nil if inner_table.nil?
 
@@ -408,6 +424,23 @@ module Exwiw
         types_need_cast?(outer_type, inner_type) ? 'text' : nil
       end
 
+      # Postgres rejects a UNION (or an `IN`) that mixes incompatible types
+      # (e.g. uuid and varchar). Examining only the first arm is not enough: a
+      # heterogeneous later arm would go uncast and break at execution. So
+      # consider the outer column together with every arm's projected column and,
+      # if ANY pair needs reconciliation, cast them all to text.
+      private def union_cast_to(union, outer_table, outer_column)
+        types = [column_pg_type(outer_table, outer_column)]
+        union.queries.each do |q|
+          col = q.columns.first
+          types << column_pg_type(q.from_table_name, col.name) if col
+        end
+        types.compact!
+
+        needs_cast = types.combination(2).any? { |a, b| types_need_cast?(a, b) }
+        needs_cast ? 'text' : nil
+      end
+
       private def escape_value(value)
         case value
         when nil

data/lib/exwiw/adapter/sqlite_adapter.rb

@@ -249,6 +249,8 @@ module Exwiw
           end
         elsif where_clause.operator == :in_subquery
           "#{key} IN (#{compile_subquery(where_clause.value)})"
+        elsif where_clause.operator == :not_null
+          "#{key} IS NOT NULL"
         else
           raise "Unsupported operator: #{where_clause.operator}"
         end
@@ -259,6 +261,12 @@ module Exwiw
         # extraction query, projected to a foreign key); compile it as-is.
         return compile_ast(subquery.query) if subquery.is_a?(Exwiw::QueryAst::SelectSubquery)
 
+        # A UnionSubquery wraps several such Selects; UNION their compiled forms
+        # into a single id set.
+        if subquery.is_a?(Exwiw::QueryAst::UnionSubquery)
+          return subquery.queries.map { |q| compile_ast(q) }.join(' UNION ')
+        end
+
         inner_values = subquery.where_values.map { |v| escape_value(v) }
         "SELECT #{subquery.table_name}.#{subquery.select_column} " \
           "FROM #{subquery.table_name} " \

data/lib/exwiw/query_ast.rb

@@ -41,7 +41,7 @@ module Exwiw
         {
           column_name: column_name,
           operator: operator,
-          value: value.is_a?(Subquery) || value.is_a?(SelectSubquery) ? value.to_h : value,
+          value: value.is_a?(Subquery) || value.is_a?(SelectSubquery) || value.is_a?(UnionSubquery) ? value.to_h : value,
         }
       end
     end
@@ -83,6 +83,25 @@ module Exwiw
       end
     end
 
+    # A subquery that UNIONs several single-column `Select`s into one id set.
+    # Used by *multi-referencer* reverse / "referenced_by" extraction
+    # (TableConfig#reverse_scope): a parent table referenced by many scoped
+    # tables is constrained to the union of every referencer's projected foreign
+    # key, rather than falling back to dumping every row:
+    #
+    #   <parent>.<pk> IN (
+    #     SELECT <ref1>.<col1> FROM <ref1> WHERE <ref1 scope> AND <col1> IS NOT NULL
+    #     UNION SELECT <ref2>.<col2> FROM <ref2> WHERE <ref2 scope> AND <col2> IS NOT NULL
+    #   )
+    #
+    # Each `queries` element is a `Select` already projected to the foreign-key
+    # column that points at the parent (with a NULL-excluding filter).
+    UnionSubquery = Struct.new(:queries, keyword_init: true) do
+      def to_h
+        { union: queries.map(&:to_h) }
+      end
+    end
+
     module ColumnValue
       Base = Struct.new(:name, :value, keyword_init: true)
       Plain = Class.new(Base)

data/lib/exwiw/query_ast_builder.rb

@@ -2,8 +2,8 @@
 
 module Exwiw
   class QueryAstBuilder
-    def self.run(table_name, table_by_name, dump_target, logger, allow_reverse: true, allow_forward: true)
-      new(table_name, table_by_name, dump_target, logger, allow_reverse: allow_reverse, allow_forward: allow_forward).run
+    def self.run(table_name, table_by_name, dump_target, logger, allow_reverse: true, forward_path: [])
+      new(table_name, table_by_name, dump_target, logger, allow_reverse: allow_reverse, forward_path: forward_path).run
     end
 
     # Scope-column mode classification for a single table. One of
@@ -49,17 +49,20 @@ module Exwiw
 
     attr_reader :table_name, :table_by_name, :dump_target
 
-    def initialize(table_name, table_by_name, dump_target, logger, allow_reverse: true, allow_forward: true)
+    def initialize(table_name, table_by_name, dump_target, logger, allow_reverse: true, forward_path: [])
       @table_name = table_name
       @table_by_name = table_by_name
       @dump_target = dump_target
       @logger = logger
       @allow_reverse = allow_reverse
-      # @allow_forward gates the "scope via an indirectly-scoped belongs_to
-      # parent" rescue (build_belongs_to_scoped_clause). Disabled while building a
-      # parent/child subquery so a single forward hop never recurses into another
-      # (which could loop on a belongs_to cycle).
-      @allow_forward = allow_forward
+      # @forward_path is the chain of tables currently being forward-resolved by
+      # the "scope via an indirectly-scoped belongs_to parent" rescue
+      # (build_belongs_to_scoped_clause). Each forward hop appends the table it is
+      # descending from, so the rescue recurses N levels (users -> end_users ->
+      # end_user_profiles -> ...) and stops only on a real belongs_to cycle: a
+      # table already on the path is not re-resolved, falling through to
+      # :unscopable instead of looping forever.
+      @forward_path = forward_path
     end
 
     def run
@@ -168,6 +171,15 @@ module Exwiw
     # such (single, unambiguous) referencer, leaving the caller to fall back to
     # the dump-all behavior.
     private def build_referenced_by_clause(table)
+      # Opt-in multi-referencer reverse scope (TableConfig#reverse_scope): when
+      # the schema author has enumerated the referencers explicitly, constrain
+      # the table to the UNION of those referencers' scoped queries instead of
+      # the single-referencer auto-detection below (which bails to a full dump
+      # once two or more tables reference the table).
+      if table.reverse_scope && table.reverse_scope.via.any?
+        return build_reverse_scope_via_clause(table)
+      end
+
       candidates = table_by_name.each_value.filter_map do |other|
         next if other.name == table.name
 
@@ -178,10 +190,11 @@ module Exwiw
         next if relation.nil? || relation.polymorphic?
 
         # Build the child's own extraction query. allow_reverse:false stops a
-        # chain of FK-less tables from recursing back into each other;
-        # allow_forward:false stops the child from forward-scoping back through
-        # this very table (which would loop).
-        child_query = self.class.run(other.name, table_by_name, dump_target, @logger, allow_reverse: false, allow_forward: false)
+        # chain of FK-less tables from recursing back into each other; adding this
+        # table to forward_path stops the child from forward-scoping back through
+        # it (which would loop) while still letting the child forward-scope
+        # through other tables.
+        child_query = self.class.run(other.name, table_by_name, dump_target, @logger, allow_reverse: false, forward_path: @forward_path + [table.name])
 
         # Only an *already constrained* child narrows anything; an unconstrained
         # child would select every fk value (i.e. dump all) and not help.
@@ -219,6 +232,64 @@ module Exwiw
       )
     end
 
+    # Multi-referencer reverse scope (TableConfig#reverse_scope). Builds a
+    # `pk IN (SELECT ref1.col1 FROM ref1 <scope> UNION SELECT ref2.col2 ...)`
+    # clause for a global-identity table referenced by many scoped tables. Each
+    # `via` arm reuses the referencer's own (already-scoped) extraction query —
+    # so a per-tenant run keeps only that tenant's ids — projected down to the
+    # foreign-key column that points at this table, with NULLs excluded.
+    #
+    # An arm whose referencer is unknown or comes out unconstrained is skipped
+    # with a warning rather than included: an unconstrained arm would project
+    # every row's id and union the whole table back, silently defeating the
+    # prune. Returns nil when no arm survives, leaving the caller to fall back to
+    # the dump-all behavior (which validate_scope! then rejects in scope mode).
+    private def build_reverse_scope_via_clause(table)
+      arms = table.reverse_scope.via.filter_map do |via|
+        referencer = table_by_name[via.table]
+        if referencer.nil?
+          @logger.warn("  #{table.name}.reverse_scope references unknown table '#{via.table}'; skipping arm.")
+          next
+        end
+
+        # Build the referencer's own scoped extraction query. allow_reverse is
+        # disabled and this table is added to forward_path to bound recursion
+        # exactly as the single-referencer path does (a referencer that could only
+        # be scoped by recursing back into this table would loop); the referencer
+        # may still forward-scope through other tables.
+        ref_query = self.class.run(referencer.name, table_by_name, dump_target, @logger, allow_reverse: false, forward_path: @forward_path + [table.name])
+
+        unless ref_query.where_clauses.any? || ref_query.join_clauses.any?
+          @logger.warn(
+            "  #{table.name}.reverse_scope arm '#{via.table}.#{via.column}' is not scoped; " \
+            "skipping it (an unconstrained arm would union every row back). " \
+            "Make '#{via.table}' scopable or remove it from reverse_scope.via."
+          )
+          next
+        end
+
+        # Project the referencer's query to the foreign-key column that points
+        # at this table, excluding NULLs. Force a plain column so any masking /
+        # raw_sql configured on that column does not corrupt the id comparison.
+        fk_column = TableColumn.from_symbol_keys(name: via.column)
+        projected = QueryAst::Select.new
+        projected.from(ref_query.from_table_name)
+        projected.select([fk_column])
+        ref_query.join_clauses.each { |j| projected.join(j) }
+        ref_query.where_clauses.each { |w| projected.where(w) }
+        projected.where(QueryAst::WhereClause.new(column_name: via.column, operator: :not_null))
+        projected
+      end
+
+      return nil if arms.empty?
+
+      QueryAst::WhereClause.new(
+        column_name: table.primary_key,
+        operator: :in_subquery,
+        value: QueryAst::UnionSubquery.new(queries: arms)
+      )
+    end
+
     # Scope-column mode. Builds a `fk IN (SELECT parent.pk FROM <parent
     # extraction query>)` clause for a table whose belongs_to parent is itself
     # scopable but carries no scope column of its own — so find_path_to_scoped
@@ -230,6 +301,13 @@ module Exwiw
     # them out of a full dump. Returns nil when there is no single, unambiguous
     # scopable parent, leaving the caller on the unscopable path.
     private def build_belongs_to_scoped_clause(table)
+      # This table plus every ancestor currently being forward-resolved. A
+      # candidate parent already on this path would close a belongs_to cycle, so
+      # it is skipped; threading the grown path into the parent build lets the
+      # cascade recurse N hops (users -> end_users -> end_user_profiles -> ...)
+      # and terminate only when a table reappears.
+      forward_path = @forward_path + [table.name]
+
       candidates = table.belongs_tos.filter_map do |relation|
         # A polymorphic belongs_to points at several parent tables through one
         # column, so it cannot project to a single parent id set; skip it.
@@ -238,10 +316,15 @@ module Exwiw
         parent = table_by_name[relation.table_name]
         next if parent.nil?
 
+        # Cycle guard: descending into a parent already on the forward path would
+        # loop (a -> b -> a). Stop, leaving this table on the :unscopable path.
+        next if forward_path.include?(parent.name)
+
         # Build the parent's own scoped query. allow_reverse stays true so the
-        # parent may be scoped via referenced_by; allow_forward:false bounds this
-        # to a single forward hop so a belongs_to cycle cannot loop.
-        parent_query = self.class.run(parent.name, table_by_name, dump_target, @logger, allow_reverse: true, allow_forward: false)
+        # parent may be scoped via referenced_by, and forward scoping stays
+        # enabled so a parent that is itself scoped via *its* parent resolves
+        # too — this is what makes the cascade multi-hop.
+        parent_query = self.class.run(parent.name, table_by_name, dump_target, @logger, allow_reverse: true, forward_path: forward_path)
 
         # Only a constrained parent narrows anything; an unconstrained parent
         # would select every pk (i.e. dump all) and not help.
@@ -393,11 +476,18 @@ module Exwiw
       return :direct if directly_scoped?(table)
       return :via_path if build_join_clauses_scoped(table).any?
       return :referenced_by if @allow_reverse && build_referenced_by_clause(table)
-      return :via_scoped_parent if @allow_forward && build_belongs_to_scoped_clause(table)
+      return :via_scoped_parent if forward_scope_allowed?(table) && build_belongs_to_scoped_clause(table)
 
       :unscopable
     end
 
+    # True when this table may still attempt the forward "scope via a scoped
+    # belongs_to parent" rescue: it is not already on the forward-resolution
+    # path, so descending into its parent cannot revisit it (a belongs_to cycle).
+    private def forward_scope_allowed?(table)
+      !@forward_path.include?(table.name)
+    end
+
     private def build_scoped(table)
       ast = QueryAst::Select.new
       ast.from(table.name)
@@ -435,11 +525,13 @@ module Exwiw
         end
       end
 
-      if @allow_forward
+      if forward_scope_allowed?(table)
         # Belongs_to a parent that is itself scoped but carries no scope column of
         # its own (so via_path cannot terminate on it) — e.g. a hub table scoped
-        # only via referenced_by. Constrain this table to that parent's in-scope
-        # ids so its rows ride along instead of being dumped in full.
+        # only via referenced_by, or a parent that is itself scoped through *its*
+        # parent. Constrain this table to that parent's in-scope ids so its rows
+        # ride along instead of being dumped in full; the parent build recurses
+        # the cascade further up.
         parent_clause = build_belongs_to_scoped_clause(table)
         if parent_clause
           ast.where(parent_clause)
@@ -447,12 +539,13 @@ module Exwiw
         end
       end
 
-      # Only the genuine top-level build (no rescue disabled) is allowed to fail
-      # hard. The Runner/ExplainRunner pre-flight (validate_scope!) rejects
-      # unscopable tables before extraction, so a top-level build never
-      # legitimately lands here; if it does, raise rather than emit an unfiltered
-      # (potential full PII) dump.
-      if @allow_reverse && @allow_forward
+      # Only the genuine top-level build (allow_reverse on, forward_path empty —
+      # i.e. no rescue subquery in progress) is allowed to fail hard. The
+      # Runner/ExplainRunner pre-flight (validate_scope!) rejects unscopable
+      # tables before extraction, so a top-level build never legitimately lands
+      # here; if it does, raise rather than emit an unfiltered (potential full
+      # PII) dump.
+      if @allow_reverse && @forward_path.empty?
         raise ArgumentError, scope_unscopable_message(table)
       end
 

data/lib/exwiw/reverse_scope.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Exwiw
+  # One referencer arm of a {ReverseScope}: the referencing table and the column
+  # on it that points at the reverse-scoped table's primary key.
+  #
+  # `column` is given explicitly so a *non-default* foreign key (e.g.
+  # `business_entity_customers.kantan_yoyaku_user_id`, or `organization_admins.id`
+  # which itself references `users.id`) can be projected — and even a column with
+  # no declared `belongs_to` edge can be enumerated.
+  class ReverseScopeVia
+    include Serdes
+
+    attribute :table, String
+    attribute :column, String
+  end
+
+  # Opt-in configuration for *multi-referencer* reverse scoping
+  # (see {QueryAstBuilder#build_referenced_by_clause}).
+  #
+  # A global-identity table such as `users` carries no scope/tenant column and
+  # has no `belongs_to` path of its own to the dump target; many tenant-owned
+  # tables instead point *at* it. The automatic single-referencer reverse
+  # extraction only narrows a table referenced by exactly one constrained child
+  # — with two or more referencers it falls back to a full dump. `reverse_scope`
+  # lets the schema author enumerate the referencers whose own (already-scoped)
+  # extraction queries should be UNION'd into the id set this table is
+  # constrained to:
+  #
+  #   <table>.<pk> IN (
+  #     SELECT <ref1>.<col1> FROM <ref1> <ref1 scope> WHERE <col1> IS NOT NULL
+  #     UNION SELECT <ref2>.<col2> FROM <ref2> <ref2 scope> WHERE <col2> IS NOT NULL
+  #     UNION ...
+  #   )
+  #
+  # It is deliberately explicit — never inferred or emitted by the schema
+  # generators, and preserved across regeneration like the other user-owned
+  # config (see {TableConfig#merge}). Only referencers that are themselves scoped
+  # belong in `via`: an unconstrained referencer would project every row's id and
+  # union the whole table back, defeating the prune (such an arm is skipped with
+  # a warning rather than silently widening the dump).
+  class ReverseScope
+    include Serdes
+
+    attribute :via, array(ReverseScopeVia), default: []
+  end
+end

data/lib/exwiw/table_config.rb

@@ -39,6 +39,14 @@ module Exwiw
     attribute :scope_exempt, Serdes::OptionalType.new(Serdes::ConcreteType.new(Boolean)), skip_serializing_if_nil: true
     attribute :scope_column, optional(String), skip_serializing_if_nil: true
 
+    # `reverse_scope` opts a table into multi-referencer reverse scoping (see
+    # Exwiw::ReverseScope and QueryAstBuilder#build_referenced_by_clause): a
+    # global-identity table (e.g. `users`) referenced by many scoped tables is
+    # constrained to the UNION of those referencers' projected foreign keys
+    # instead of being dumped in full. User-configured and never emitted by the
+    # schema generators.
+    attribute :reverse_scope, Serdes::OptionalType.new(ReverseScope), skip_serializing_if_nil: true
+
     def self.from(hash)
       config = super
       config.send(:validate_after_load!)
@@ -58,6 +66,7 @@ module Exwiw
       if rails_managed?
         hash.delete("belongs_tos")
         hash.delete("columns")
+        hash.delete("reverse_scope")
       end
       hash
     end
@@ -152,6 +161,7 @@ module Exwiw
         # User-owned, never regenerated: carry over from the existing config.
         merged_table.scope_exempt = scope_exempt
         merged_table.scope_column = scope_column
+        merged_table.reverse_scope = reverse_scope
 
         # Structural facts of each belongs_to come from the freshly generated
         # config, but the user-owned `comment`/`ignore`/`ignore_type`/`references`
@@ -199,6 +209,10 @@ module Exwiw
           raise ArgumentError,
                 "Table '#{name}' has type=#{type}; columns must not be defined."
         end
+        if reverse_scope
+          raise ArgumentError,
+                "Table '#{name}' has type=#{type}; reverse_scope must not be defined."
+        end
       else
         # An ignore:true table is not extracted, so primary_key is not required
         # (e.g. a composite-primary-key table that exwiw does not support).

data/lib/exwiw/version.rb

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

data/lib/exwiw.rb

@@ -9,6 +9,7 @@ require_relative "exwiw/ext_json"
 require_relative "exwiw/config_file"
 require_relative "exwiw/belongs_to"
 require_relative "exwiw/table_column"
+require_relative "exwiw/reverse_scope"
 require_relative "exwiw/table_config"
 require_relative "exwiw/embedded_in"
 require_relative "exwiw/mongodb_field"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exwiw
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.3
 platform: ruby
 authors:
 - Shia
@@ -76,6 +76,7 @@ files:
 - lib/exwiw/query_ast.rb
 - lib/exwiw/query_ast_builder.rb
 - lib/exwiw/railtie.rb
+- lib/exwiw/reverse_scope.rb
 - lib/exwiw/runner.rb
 - lib/exwiw/schema_generator.rb
 - lib/exwiw/table_column.rb