dag_me 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 315af993cc34ae379f332dd02f4000562cf48085367a5807d711a564222c84c8
-  data.tar.gz: 037e69f2e9b9ece91340c0445c6a29ba68daaf43088a59cf6315ffa1c03dfd2b
+  metadata.gz: c1012817d36f748b2056aec9ea431941bccab8abb2f9e28bb6e1cf576dc40c87
+  data.tar.gz: 18e716d54532f6a25605454dcc1ae08fe91d3e1f6c54dca5e39ede20a2fe8ba2
 SHA512:
-  metadata.gz: 8f7e8e4eaa02964bea7ad772989ce878bff46d3275d5e6b69858fa5d3901439d9a808628012c3c6c724153ab4fc9e8fed4458c9bbb34cf153adb3fb7d5e0c891
-  data.tar.gz: 0ab38c6617793a3e48586e9e5bd58969e2a96980d13736ef90d864141b93816e8241bef552f4cf3f242c95150b40634491489e79f80e202e4a6a705c9fabb080
+  metadata.gz: 43b71fef3c469db2e0fbeb5ee2b8831a8ae9553015d813c68cbe72004db61c25ca5154a71563579ca0100e4f7839c0553edaa706037906be9d8b7a84200532c2
+  data.tar.gz: 05ef5140aa9a23e43f02414179a55ce9849b8b7809d1eb5923378bda3bacd1e3032ab89a73384081eefcc8a0d69011a3642c8f8e1e4cff7324618fedabed3f2a

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.5.0](https://github.com/ClosureTree/dag_me/compare/v0.4.2...v0.5.0) (2026-10-06)
+
+
+### Bug Fixes
+
+* keep the dev bundle off activerecord 8.1.4 ([b488d73](https://github.com/ClosureTree/dag_me/commit/b488d735e945ecaef270045e8a53254b9558b8f2))
+* recompute the closure without enumerating paths ([498c9dc](https://github.com/ClosureTree/dag_me/commit/498c9dced5d899de1c3ecd140accdda9f0c5c658))

data/README.md

@@ -89,7 +89,7 @@ For a `missions` table:
 | `mission_dag_edge_insert_apply` | `AFTER INSERT`: incremental closure expansion |
 | `mission_dag_edge_delete_apply` | `AFTER DELETE`: exact `path_count` decrement + `min_depth` repair |
 | `mission_dag_node_insert` / `mission_dag_node_delete` | Self-row lifecycle, edge teardown through triggers |
-| `mission_dag_rebuild_paths()` / `mission_dag_validate_paths()` | Rebuild from edges / diff against CTE truth |
+| `mission_dag_rebuild_paths()` / `mission_dag_validate_paths()` | Rebuild from edges / diff against a recomputation from edges |
 
 Generated by [rails_lens](https://github.com/seuros/rails_lens) from the test app
 (`make erd`); it reflects the runtime classes dag_me defines, so your own models
@@ -299,7 +299,8 @@ flowchart LR
   path counts explode combinatorially in dense DAGs).
 - `min_depth` is the shortest-path length. Deleting an edge triggers exact decremental
   maintenance: contributions through the deleted edge are subtracted, zero-count pairs
-  are dropped, and `min_depth` is repaired by fixpoint iteration.
+  are dropped, and `min_depth` is repaired: only pairs whose shortest path ran through
+  the deleted edge are recomputed, and changes propagate upward until nothing moves.
 - Edge deletion in dense graphs is the expensive operation, by design. Reads are cheap,
   inserts are `ancestors(parent) × descendants(child)`, deletes pay for exactness.
 - Concurrent writers are serialized per graph with `pg_advisory_xact_lock` - two
@@ -310,6 +311,12 @@ flowchart LR
   an in-flight edge into a cross-tenant graph.
 - Destroying a node tears down its edges through the triggers (not FK-cascade ordering),
   so the closure shrinks correctly.
+- `rebuild!` and `validate` recompute the closure from the edges layer by layer (nodes
+  grouped by their longest distance from a root), so their cost is polynomial no matter
+  how many paths the graph holds. They use temp tables, so they need a writable
+  connection, and they raise `DagMe::CycleError` if edges written with triggers disabled
+  form a cycle. `validate` runs in its own REPEATABLE READ transaction; inside yours it
+  holds SHARE locks on the node and edge tables instead, so writers wait until it ends.
 
 ## Rake tasks
 
@@ -318,6 +325,20 @@ rake dag_me:status          # doctor report per network: tables, triggers, funct
 rake dag_me:rebuild         # rebuild every closure (or MODEL=Mission for one)
 ```
 
+## Upgrading
+
+The triggers and functions live in your database, so a gem upgrade that changes them
+needs a migration. Function bodies are stamped with `DagMe::DDL::REVISION`, and
+`rake dag_me:status` flags graphs installed by an older one. Generate a refresh per model:
+
+```bash
+rails generate dag_me:refresh Mission
+```
+
+The migration calls `DagMe::DDL.refresh!(Mission)`, which replaces every function body
+with `CREATE OR REPLACE` and reapplies the closure table's storage settings. Tables,
+triggers, and rows are left alone.
+
 ## Testing your app's graphs
 
 The gem ships Minitest assertions for host applications:
@@ -343,13 +364,14 @@ All assertions accept `dag:` for named networks.
 
 ```bash
 make up      # postgres:18 via docker compose (port 5438)
-make check   # rubocop + full suite
+make check   # dictator lint + full suite
 ```
 
 The suite includes property tests that apply random edge insertions, edge deletions,
-and node destructions (single- and multi-tenant) and validate the closure against
-recursive-CTE truth after every single operation, plus concurrency tests racing
-reverse edges across threads.
+and node destructions (single- and multi-tenant) and validate the closure against a
+recomputation from the edges after every single operation, plus concurrency tests racing
+reverse edges across threads. The recomputation itself is checked against brute-force
+path enumeration on small random graphs.
 
 Large graph fixtures are generated, not committed: [vial](https://rubygems.org/gems/vial)
 compiles `test/vials/*.vial.rb` into deterministic YAML fixtures at test boot

data/lib/dag_me/configuration.rb

@@ -29,7 +29,7 @@ module DagMe
       # Ivar peek keeps class load DB-free; composite keys must be declared
       # before the macro. Array === because AR seeds a BasicObject sentinel.
       @composite_pk = model.instance_variable_defined?(:@primary_key) &&
-                      Array === model.instance_variable_get(:@primary_key) # rubocop:disable Style/CaseEquality
+                      Array === model.instance_variable_get(:@primary_key)
     end
 
     def closure?

data/lib/dag_me/ddl.rb

@@ -17,7 +17,11 @@ module DagMe
   #   task_dag_node_update        -- BEFORE UPDATE on tasks: scope-change guard (scoped only)
   #   task_dag_node_delete        -- BEFORE DELETE on tasks: drop edges through triggers
   #   task_dag_rebuild_paths()    -- full closure rebuild from edges
-  #   task_dag_validate_paths()   -- closure vs recursive-CTE truth diff
+  #   task_dag_validate_paths()   -- stored closure vs closure recomputed from edges
+  #
+  # rebuild and validate share truth_sql: a layered recomputation that is
+  # polynomial in the graph size. Function bodies are stamped with REVISION;
+  # refresh! upgrades an installed graph in place.
   #
   # Node identity is an ordered column list (Configuration#node_pk_columns):
   # single-key models get the classic parent_id / child_id / ancestor_id /
@@ -35,6 +39,17 @@ module DagMe
   # The paths table and its triggers are skipped for maintain: :recursive_cte;
   # cycle rejection then uses a recursive CTE in the BEFORE INSERT trigger.
   class DDL
+    # Bumped whenever generated function bodies change. Stamped onto the lock
+    # function, so `dag_me:status` can spot installs that predate a fix.
+    REVISION = 2
+
+    # Free space left in every closure page. Writes update path_count and
+    # min_depth, neither indexed, so with room on the page PostgreSQL can
+    # update in place (HOT) and skip both index inserts: on a dense
+    # 1,000-node graph that took HOT updates from 27% to 97% and halved
+    # mid-graph edge writes.
+    PATHS_FILLFACTOR = 70
+
     class << self
       # Installs / removes the SQL objects for every dag the model declares.
       def install!(model)
@@ -44,6 +59,12 @@ module DagMe
       def uninstall!(model)
         model.dag_configs.each_value { |config| new(config).uninstall! }
       end
+
+      # Replaces the function bodies of an installed graph with the current
+      # revision. Tables, triggers, and data are left alone.
+      def refresh!(model)
+        model.dag_configs.each_value { |config| new(config).refresh! }
+      end
     end
 
     attr_reader :config
@@ -60,22 +81,47 @@ module DagMe
       execute_all(uninstall_sql)
     end
 
+    # Function bodies plus the closure's storage settings. Tables, triggers,
+    # and rows are left alone; existing pages gain free space as they are
+    # rewritten (VACUUM FULL, or rows updated over time).
+    def refresh!
+      execute_all(function_sql + storage_sql)
+    end
+
+    def storage_sql
+      return [] unless config.closure?
+
+      ["ALTER TABLE #{config.paths_table} SET (fillfactor = #{PATHS_FILLFACTOR});"]
+    end
+
     def install_sql
       statements = [edges_table_sql]
-      if config.closure?
-        statements << paths_table_sql
-        statements.concat(closure_function_sql)
-        statements.concat(closure_trigger_sql)
-        statements << backfill_self_rows_sql
-        statements << rebuild_function_sql
-        statements << validate_function_sql
-      else
-        statements.concat(cte_function_sql)
-        statements.concat(cte_trigger_sql)
-      end
+      statements << paths_table_sql if config.closure?
+      statements.concat(function_sql)
+      statements.concat(config.closure? ? closure_trigger_sql : cte_trigger_sql)
+      statements << backfill_self_rows_sql if config.closure?
       statements
     end
 
+    # Every function as CREATE OR REPLACE, plus the revision stamp. Re-running
+    # it on an installed graph is how refresh! upgrades in place.
+    def function_sql
+      statements = if config.closure?
+                     closure_function_sql + [rebuild_function_sql, validate_function_sql]
+                   else
+                     cte_function_sql
+                   end
+      statements << revision_comment_sql
+    end
+
+    def revision_comment_sql
+      "COMMENT ON FUNCTION #{config.function_ref('lock')}(text) IS '#{self.class.revision_tag}';"
+    end
+
+    def self.revision_tag
+      "dag_me ddl revision #{REVISION}"
+    end
+
     # Graph#backfill_self_rows! reuses this to repair nodes inserted with
     # triggers disabled (e.g. Rails fixture loading).
     def backfill_self_rows_sql
@@ -221,7 +267,7 @@ module DagMe
           FOREIGN KEY #{tuple(anc_cols)} REFERENCES #{config.node_table} #{tuple(pk_cols)} ON DELETE CASCADE,
           FOREIGN KEY #{tuple(desc_cols)} REFERENCES #{config.node_table} #{tuple(pk_cols)} ON DELETE CASCADE,
           PRIMARY KEY (#{list(anc_cols)}, #{list(desc_cols)})
-        );
+        ) WITH (fillfactor = #{PATHS_FILLFACTOR});
         CREATE INDEX ON #{config.paths_table} (#{list(desc_cols)}, #{list(anc_cols)});
       SQL
     end
@@ -315,6 +361,47 @@ module DagMe
       SQL
     end
 
+    def x_cols
+      pk_cols.map { |c| "x_#{c}" }
+    end
+
+    def y_cols
+      pk_cols.map { |c| "y_#{c}" }
+    end
+
+    # Every pair (x, y) whose paths run through the edge `row` (NEW or OLD):
+    # x reaches the edge's parent, the edge's child reaches y. `through` is
+    # how many x -> y paths use the edge, `via_depth` the shortest of them.
+    def through_edge_sql(row)
+      x = anc_cols.zip(x_cols).map { |a, c| "a.#{a} AS #{c}" }.join(', ')
+      y = desc_cols.zip(y_cols).map { |d, c| "d.#{d} AS #{c}" }.join(', ')
+      <<~SQL.chomp
+        SELECT #{x}, #{y},
+                 a.path_count * d.path_count AS through,
+                 a.min_depth + 1 + d.min_depth AS via_depth
+          FROM #{config.paths_table} a
+          JOIN #{config.paths_table} d ON #{eq(anc_cols, child_cols, left: 'd', right: row)}
+          WHERE #{eq(desc_cols, parent_cols, left: 'a', right: row)}
+      SQL
+    end
+
+    # "p.ancestor_id = r.x_id AND p.descendant_id = r.y_id"
+    def pair_match(row = 'r', target: 'p')
+      "#{eq(anc_cols, x_cols, left: target, right: row)} AND #{eq(desc_cols, y_cols, left: target, right: row)}"
+    end
+
+    # Shortest distance from w's x to w's y over x's remaining out-edges.
+    def recomputed_depth_sql(row)
+      <<~SQL.chomp
+        SELECT MIN(1 + cp.min_depth) AS new_depth
+              FROM #{config.edge_table} e
+              JOIN #{config.paths_table} cp
+                ON #{eq(anc_cols, child_cols, left: 'cp', right: 'e')}
+               AND #{eq(desc_cols, y_cols, left: 'cp', right: row)}
+              WHERE #{eq(parent_cols, x_cols, left: 'e', right: row)}
+      SQL
+    end
+
     def edge_insert_apply_sql
       paths = config.paths_table
       <<~SQL
@@ -340,75 +427,79 @@ module DagMe
 
     def edge_delete_apply_sql
       p = config.prefix
-      edges = config.edge_table
       paths = config.paths_table
-      x_cols = pk_cols.map { |c| "x_#{c}" }
-      y_cols = pk_cols.map { |c| "y_#{c}" }
-      rect_defs = (col_defs(x_cols) + col_defs(y_cols)).map { |d| "    #{d}," }.join("\n")
+      edges = config.edge_table
+      work_defs = (col_defs(x_cols) + col_defs(y_cols)).map { |d| "    #{d}" }.join(",\n")
       <<~SQL
         CREATE OR REPLACE FUNCTION #{config.function_ref('edge_delete_apply')}() RETURNS trigger
         LANGUAGE plpgsql AS $$
         BEGIN
           PERFORM #{config.function_ref('lock')}(#{scope_key_expr('OLD')});
 
-          -- The affected rectangle: every pair (x, y) with x reaching OLD's parent
-          -- and OLD's child reaching y lost `removed` paths through this edge.
-          -- Multipliers cannot themselves traverse the deleted edge (that would
-          -- imply a cycle), so pre-decrement closure values are exact here.
-          CREATE TEMP TABLE IF NOT EXISTS #{p}_delete_rect (
-        #{rect_defs}
-            removed numeric NOT NULL,
-            via_depth integer NOT NULL,
-            PRIMARY KEY (#{list(x_cols)}, #{list(y_cols)})
+          -- Every pair through the deleted edge loses `through` paths: pairs
+          -- left with none are dropped, the rest decremented. Multipliers
+          -- cannot traverse the deleted edge (that would imply a cycle), so
+          -- the closure rows they come from are untouched here.
+          WITH r AS MATERIALIZED (
+            #{through_edge_sql('OLD')}
+          ),
+          gone AS (
+            DELETE FROM #{paths} p USING r
+            WHERE #{pair_match} AND p.path_count <= r.through
+          )
+          UPDATE #{paths} p
+          SET path_count = p.path_count - r.through
+          FROM r
+          WHERE #{pair_match} AND p.path_count > r.through;
+
+          -- min_depth repair. Only a surviving pair whose shortest path ran
+          -- through the edge (min_depth = via_depth) can get longer:
+          --   min_depth(x, y) = min(1 + min_depth(c, y)) over edges x -> c
+          -- Pairs that change go to a worklist; their parents' pairs are
+          -- recomputed until nothing changes. Values only grow, from below.
+          CREATE TEMP TABLE IF NOT EXISTS #{p}_depth_work (
+        #{work_defs}
           ) ON COMMIT DROP;
-          DELETE FROM #{p}_delete_rect;
-
-          INSERT INTO #{p}_delete_rect (#{list(x_cols)}, #{list(y_cols)}, removed, via_depth)
-          SELECT #{list(anc_cols, 'a')}, #{list(desc_cols, 'd')},
-                 a.path_count * d.path_count,
-                 a.min_depth + 1 + d.min_depth
-          FROM #{paths} a
-          JOIN #{paths} d ON #{eq(anc_cols, child_cols, left: 'd', right: 'OLD')}
-          WHERE #{eq(desc_cols, parent_cols, left: 'a', right: 'OLD')};
+          DELETE FROM #{p}_depth_work;
 
-          UPDATE #{paths} p
-          SET path_count = p.path_count - r.removed
-          FROM #{p}_delete_rect r
-          WHERE #{eq(anc_cols, x_cols, left: 'p', right: 'r')}
-            AND #{eq(desc_cols, y_cols, left: 'p', right: 'r')};
-
-          DELETE FROM #{paths} p
-          USING #{p}_delete_rect r
-          WHERE #{eq(anc_cols, x_cols, left: 'p', right: 'r')}
-            AND #{eq(desc_cols, y_cols, left: 'p', right: 'r')}
-            AND p.path_count <= 0;
-
-          -- min_depth repair: surviving rectangle pairs may have lost their
-          -- shortest path. Iterate the recurrence
-          --   min_depth(x, y) = min(1 + min_depth(c, y)) over edges x -> c reaching y
-          -- until fixpoint; converges in at most longest-affected-chain steps.
-          LOOP
+          WITH r AS MATERIALIZED (
+            #{through_edge_sql('OLD')}
+          ),
+          raised AS (
             UPDATE #{paths} p
-            SET min_depth = fix.new_md
-            FROM (
-              SELECT #{list(anc_cols, 's')}, #{list(desc_cols, 's')},
-                     (SELECT MIN(1 + cp.min_depth)
-                      FROM #{edges} e
-                      JOIN #{paths} cp
-                        ON #{eq(anc_cols, child_cols, left: 'cp', right: 'e')}
-                       AND #{eq(desc_cols, desc_cols, left: 'cp', right: 's')}
-                      WHERE #{eq(parent_cols, anc_cols, left: 'e', right: 's')}) AS new_md
-              FROM #{paths} s
-              JOIN #{p}_delete_rect r
-                ON #{eq(x_cols, anc_cols, left: 'r', right: 's')}
-               AND #{eq(y_cols, desc_cols, left: 'r', right: 's')}
-              WHERE #{tuple(anc_cols, 's')} <> #{tuple(desc_cols, 's')}
-            ) fix
-            WHERE #{eq(anc_cols, anc_cols, left: 'p', right: 'fix')}
-              AND #{eq(desc_cols, desc_cols, left: 'p', right: 'fix')}
-              AND fix.new_md IS NOT NULL
-              AND fix.new_md <> p.min_depth;
-            EXIT WHEN NOT FOUND;
+            SET min_depth = m.new_depth
+            FROM r
+            CROSS JOIN LATERAL (
+              #{recomputed_depth_sql('r')}
+            ) m
+            WHERE #{pair_match}
+              AND p.min_depth = r.via_depth
+              AND m.new_depth > p.min_depth
+            RETURNING #{list(anc_cols, 'p')}, #{list(desc_cols, 'p')}
+          )
+          INSERT INTO #{p}_depth_work SELECT * FROM raised;
+
+          WHILE EXISTS (SELECT 1 FROM #{p}_depth_work) LOOP
+            WITH done AS (
+              DELETE FROM #{p}_depth_work RETURNING *
+            ),
+            w AS (
+              SELECT DISTINCT #{parent_cols.zip(x_cols).map { |pc, x| "e.#{pc} AS #{x}" }.join(', ')}, #{list(y_cols, 'd')}
+              FROM done d
+              JOIN #{edges} e ON #{eq(child_cols, x_cols, left: 'e', right: 'd')}
+            ),
+            raised AS (
+              UPDATE #{paths} p
+              SET min_depth = m.new_depth
+              FROM w
+              CROSS JOIN LATERAL (
+                #{recomputed_depth_sql('w')}
+              ) m
+              WHERE #{pair_match('w')}
+                AND m.new_depth > p.min_depth
+              RETURNING #{list(anc_cols, 'p')}, #{list(desc_cols, 'p')}
+            )
+            INSERT INTO #{p}_depth_work SELECT * FROM raised;
           END LOOP;
 
           RETURN NULL;
@@ -499,48 +590,139 @@ module DagMe
       SQL
     end
 
-    def truth_walk_sql
+    # Scratch tables for truth_sql: one row per node with its layer, and the
+    # closure being computed. Temp, dropped at commit.
+    def truth_scratch_sql
+      p = config.prefix
+      layer_defs = col_defs(pk_cols).map { |d| "  #{d}," }.join("\n")
+      truth_defs = (col_defs(anc_cols) + col_defs(desc_cols)).map { |d| "  #{d}," }.join("\n")
+      <<~SQL.chomp
+        CREATE TEMP TABLE IF NOT EXISTS #{p}_layer (
+        #{layer_defs}
+          layer integer NOT NULL,
+          PRIMARY KEY (#{list(pk_cols)})
+        ) ON COMMIT DROP;
+        CREATE INDEX IF NOT EXISTS #{p}_layer_by_layer ON #{p}_layer (layer);
+        DELETE FROM #{p}_layer;
+        CREATE TEMP TABLE IF NOT EXISTS #{p}_truth (
+        #{truth_defs}
+          min_depth integer NOT NULL,
+          path_count numeric NOT NULL,
+          PRIMARY KEY (#{list(desc_cols)}, #{list(anc_cols)})
+        ) ON COMMIT DROP;
+        DELETE FROM #{p}_truth;
+      SQL
+    end
+
+    # Computes the exact closure from the edges into <prefix>_truth, without
+    # walking paths one by one (path counts grow exponentially with every
+    # diamond, so an enumerating walk does too).
+    #
+    # Nodes are layered by their longest distance from a root, one set-based
+    # INSERT per layer. Every parent of a layer-L node sits in a lower layer,
+    # so one aggregate per layer extends the parents' finished rows:
+    #
+    #   path_count(a, v) = sum of path_count(a, u) over edges u -> v
+    #   min_depth(a, v)  = 1 + min of min_depth(a, u) over edges u -> v
+    #
+    # Nodes left without a layer sit on or below a cycle, which only edges
+    # written with triggers disabled can produce: raise DGME1.
+    #
+    # Expects `depth integer` declared by the enclosing function.
+    def truth_sql
+      p = config.prefix
+      edges = config.edge_table
+      node = config.node_table
       <<~SQL.chomp
-        WITH RECURSIVE walk(#{list(anc_cols)}, #{list(desc_cols)}, depth) AS (
-          SELECT #{list(parent_cols)}, #{list(child_cols)}, 1 FROM #{config.edge_table}
-          UNION ALL
-          SELECT #{list(anc_cols, 'w')}, #{list(child_cols, 'e')}, w.depth + 1
-          FROM walk w
-          JOIN #{config.edge_table} e ON #{eq(parent_cols, desc_cols, left: 'e', right: 'w')}
-        )
+        #{truth_scratch_sql}
+
+        INSERT INTO #{p}_layer (#{list(pk_cols)}, layer)
+        SELECT #{list(pk_cols, 'n')}, 0 FROM #{node} n
+        WHERE NOT EXISTS (SELECT 1 FROM #{edges} e WHERE #{eq(child_cols, pk_cols, left: 'e', right: 'n')});
+
+        depth := 0;
+        LOOP
+          depth := depth + 1;
+          -- children of the previous layer whose parents all have a layer
+          INSERT INTO #{p}_layer (#{list(pk_cols)}, layer)
+          SELECT DISTINCT #{list(child_cols, 'e')}, depth
+          FROM #{p}_layer f
+          JOIN #{edges} e ON #{eq(parent_cols, pk_cols, left: 'e', right: 'f')}
+          WHERE f.layer = depth - 1
+            AND NOT EXISTS (
+              SELECT 1 FROM #{edges} w
+              WHERE #{eq(child_cols, child_cols, left: 'w', right: 'e')}
+                AND NOT EXISTS (SELECT 1 FROM #{p}_layer q WHERE #{eq(pk_cols, parent_cols, left: 'q', right: 'w')})
+            );
+          EXIT WHEN NOT FOUND;
+        END LOOP;
+
+        IF (SELECT count(*) FROM #{p}_layer) < (SELECT count(*) FROM #{node}) THEN
+          RAISE EXCEPTION 'dag_me: % contains a cycle (edges written with triggers disabled?)', '#{edges}'
+            USING ERRCODE = '#{SQLSTATE_CYCLE}';
+        END IF;
+
+        INSERT INTO #{p}_truth (#{list(anc_cols)}, #{list(desc_cols)}, min_depth, path_count)
+        SELECT #{list(pk_cols)}, #{list(pk_cols)}, 0, 1 FROM #{node};
+
+        FOR step IN 1 .. depth - 1 LOOP
+          INSERT INTO #{p}_truth (#{list(anc_cols)}, #{list(desc_cols)}, min_depth, path_count)
+          SELECT #{list(anc_cols, 't')}, #{list(child_cols, 'e')}, MIN(t.min_depth) + 1, SUM(t.path_count)
+          FROM #{p}_layer v
+          JOIN #{edges} e ON #{eq(child_cols, pk_cols, left: 'e', right: 'v')}
+          JOIN #{p}_truth t ON #{eq(desc_cols, parent_cols, left: 't', right: 'e')}
+          WHERE v.layer = step
+          GROUP BY #{list(anc_cols, 't')}, #{list(child_cols, 'e')};
+        END LOOP;
       SQL
     end
 
+    # ", n.account_id" (leading comma) or "" - scope taken from the ancestor
+    # node, joined as `n` by truth_scope_join.
+    def truth_scope_select
+      config.scope_columns.map { |c| ", n.#{c}" }.join
+    end
+
+    def truth_scope_join
+      return '' unless scoped?
+
+      " JOIN #{config.node_table} n ON #{eq(pk_cols, anc_cols, left: 'n', right: 't')}"
+    end
+
     def rebuild_function_sql
-      scope_join = scoped? ? "JOIN #{config.node_table} n ON #{eq(pk_cols, anc_cols, left: 'n', right: 'walk')}" : ''
-      scope_group = config.scope_columns.map { |c| ", n.#{c}" }.join
       <<~SQL
         CREATE OR REPLACE FUNCTION #{config.function_ref('rebuild_paths')}() RETURNS void
         LANGUAGE plpgsql AS $$
+        DECLARE
+          depth integer;
         BEGIN
           LOCK TABLE #{config.node_table}, #{config.edge_table} IN SHARE ROW EXCLUSIVE MODE;
-          DELETE FROM #{config.paths_table};
 
-          INSERT INTO #{config.paths_table} (#{list(anc_cols)}, #{list(desc_cols)}, min_depth, path_count#{scope_column_list})
-          SELECT #{list(pk_cols)}, #{list(pk_cols)}, 0, 1#{scope_column_list} FROM #{config.node_table};
+        #{truth_sql.gsub(/^/, '  ')}
 
-          #{truth_walk_sql}
+          DELETE FROM #{config.paths_table};
           INSERT INTO #{config.paths_table} (#{list(anc_cols)}, #{list(desc_cols)}, min_depth, path_count#{scope_column_list})
-          SELECT #{list(anc_cols, 'walk')}, #{list(desc_cols, 'walk')}, MIN(depth), COUNT(*)::numeric#{scope_group}
-          FROM walk #{scope_join}
-          GROUP BY #{list(anc_cols, 'walk')}, #{list(desc_cols, 'walk')}#{scope_group};
+          SELECT #{list(anc_cols, 't')}, #{list(desc_cols, 't')}, t.min_depth, t.path_count#{truth_scope_select}
+          FROM #{config.prefix}_truth t#{truth_scope_join};
         END;
         $$;
       SQL
     end
 
+    # The truth is computed across several statements. Inside a REPEATABLE
+    # READ (or stricter) transaction they share one snapshot; under READ
+    # COMMITTED each statement would see fresh data, so writers are held off
+    # with SHARE locks for the duration instead.
     def validate_function_sql
-      scope_join = scoped? ? "JOIN #{config.node_table} n ON #{eq(pk_cols, anc_cols, left: 'n', right: 'walk')}" : ''
-      scope_group = config.scope_columns.map { |c| ", n.#{c}" }.join
       scope_mismatch = scoped? ? "OR #{scope_distinct_expr('s', 't')}" : ''
       returns = (col_defs(anc_cols, not_null: false) + col_defs(desc_cols, not_null: false))
                 .map { |d| "  #{d}," }.join("\n")
       coalesced = (anc_cols + desc_cols).map { |c| "COALESCE(t.#{c}, s.#{c})" }.join(",\n                 ")
+      truth = if scoped?
+                "(SELECT t.*#{truth_scope_select} FROM #{config.prefix}_truth t#{truth_scope_join})"
+              else
+                "#{config.prefix}_truth"
+              end
       <<~SQL
         CREATE OR REPLACE FUNCTION #{config.function_ref('validate_paths')}()
         RETURNS TABLE(
@@ -550,18 +732,22 @@ module DagMe
           true_min_depth integer,
           true_path_count numeric
         )
-        LANGUAGE sql AS $$
-          #{truth_walk_sql}, truth AS (
-            SELECT #{list(anc_cols, 'walk')}, #{list(desc_cols, 'walk')}, MIN(depth) AS min_depth, COUNT(*)::numeric AS path_count#{scope_group}
-            FROM walk #{scope_join}
-            GROUP BY #{list(anc_cols, 'walk')}, #{list(desc_cols, 'walk')}#{scope_group}
-            UNION ALL
-            SELECT #{list(pk_cols)}, #{list(pk_cols)}, 0, 1::numeric#{scope_column_list} FROM #{config.node_table}
-          )
+        LANGUAGE plpgsql AS $$
+        #variable_conflict use_column
+        DECLARE
+          depth integer;
+        BEGIN
+          IF current_setting('transaction_isolation') IN ('read committed', 'read uncommitted') THEN
+            LOCK TABLE #{config.node_table}, #{config.edge_table} IN SHARE MODE;
+          END IF;
+
+        #{truth_sql.gsub(/^/, '  ')}
+
+          RETURN QUERY
           SELECT #{coalesced},
                  s.min_depth, s.path_count,
                  t.min_depth, t.path_count
-          FROM truth t
+          FROM #{truth} t
           FULL OUTER JOIN #{config.paths_table} s
             ON #{eq(anc_cols, anc_cols, left: 's', right: 't')}
            AND #{eq(desc_cols, desc_cols, left: 's', right: 't')}
@@ -570,6 +756,7 @@ module DagMe
              OR s.min_depth <> t.min_depth
              OR s.path_count <> t.path_count
              #{scope_mismatch};
+        END;
         $$;
       SQL
     end

data/lib/dag_me/errors.rb

@@ -16,7 +16,7 @@ module DagMe
   class IsolationError < Error; end
 
   # Raised by Graph#validate! when the stored closure disagrees with the
-  # recursive-CTE truth. Carries the offending rows.
+  # closure recomputed from the edges. Carries the offending rows.
   class CorruptionError < Error
     attr_reader :discrepancies
 

data/lib/dag_me/graph.rb

@@ -51,7 +51,9 @@ module DagMe
       return self unless config.closure?
 
       model.connection_pool.with_connection do |conn|
-        conn.execute("SELECT #{conn.quote_table_name(config.function_ref('rebuild_paths'))}();")
+        DagMe.translate_errors do
+          conn.execute("SELECT #{conn.quote_table_name(config.function_ref('rebuild_paths'))}();")
+        end
       end
       self
     end
@@ -68,13 +70,19 @@ module DagMe
       self
     end
 
-    # Rows where the stored closure disagrees with the recursive-CTE truth.
-    # Empty means healthy.
+    # Rows where the stored closure disagrees with the closure recomputed
+    # from the edges. Empty means healthy. Raises CycleError when the edges
+    # themselves contain a cycle (possible only with triggers disabled).
+    # Needs a writable connection: the recomputation uses temp tables.
     def validate
       return [] unless config.closure?
 
       model.connection_pool.with_connection do |conn|
-        conn.select_all("SELECT * FROM #{conn.quote_table_name(config.function_ref('validate_paths'))}();").to_a
+        DagMe.translate_errors do
+          with_stable_snapshot(conn) do
+            conn.select_all("SELECT * FROM #{conn.quote_table_name(config.function_ref('validate_paths'))}();").to_a
+          end
+        end
       end
     end
 
@@ -92,5 +100,16 @@ module DagMe
 
       self
     end
+
+    private
+
+    # validate_paths() reads the graph across several statements. Its own
+    # REPEATABLE READ transaction gives them one snapshot without blocking
+    # writers; inside a caller's transaction the function locks instead.
+    def with_stable_snapshot(conn, &)
+      return yield if conn.transaction_open?
+
+      conn.transaction(isolation: :repeatable_read, &)
+    end
   end
 end

data/lib/dag_me/railtie.rb

@@ -6,6 +6,7 @@ module DagMe
   class Railtie < Rails::Railtie # :nodoc:
     generators do
       require_relative '../generators/dag_me/migration_generator'
+      require_relative '../generators/dag_me/refresh_generator'
     end
 
     rake_tasks do

data/lib/dag_me/task_helpers.rb

@@ -46,6 +46,7 @@ module DagMe
       lines.concat(table_checks(model, config))
       lines.concat(trigger_checks(model, config))
       lines.concat(function_checks(model, config))
+      lines << revision_line(model, installed_revision(model, config))
       lines << closure_check(model, config)
       "#{lines.compact.join("\n  ")}\n"
     end
@@ -111,6 +112,31 @@ module DagMe
       'n.nspname = ANY (current_schemas(false))'
     end
 
+    # Function bodies carry the DDL revision they were generated from (a
+    # comment on the lock function). :current, :outdated, or nil when the
+    # lock function is missing (function_checks already reports that).
+    def installed_revision(model, config)
+      conn = model.connection
+      stamps = conn.select_values(<<~SQL)
+        SELECT COALESCE(obj_description(p.oid, 'pg_proc'), '') FROM pg_proc p
+        JOIN pg_namespace n ON n.oid = p.pronamespace
+        WHERE #{namespace_filter(conn, config)}
+          AND p.proname = #{conn.quote("#{config.prefix}_lock")}
+      SQL
+      return nil if stamps.empty?
+
+      stamps.first == DDL.revision_tag ? :current : :outdated
+    end
+
+    def revision_line(model, revision)
+      case revision
+      when :current then ok("functions at revision #{DDL::REVISION}")
+      when :outdated
+        bad("functions predate revision #{DDL::REVISION} - run `rails generate dag_me:refresh #{model.name}` " \
+            'and migrate')
+      end
+    end
+
     def closure_check(model, config)
       return ok('closure: not materialized (recursive_cte)') unless config.closure?
       return nil unless model.connection.table_exists?(config.paths_table)
@@ -123,6 +149,8 @@ module DagMe
         facade = config.default? ? 'Model.dag' : "Model.dag(:#{config.name})"
         bad("closure diverged: #{discrepancies.length} rows - run #{facade}.rebuild!")
       end
+    rescue CycleError
+      bad("#{config.edge_table} contains a cycle - edges were written with triggers disabled")
     end
   end
 end

data/lib/dag_me/test_helper.rb

@@ -29,7 +29,7 @@ module DagMe
                    "#{klass} should be scoped by #{Array(scope).join(', ')}"
     end
 
-    # Asserts the stored closure agrees with the recursive-CTE truth.
+    # Asserts the stored closure agrees with the closure recomputed from the edges.
     def assert_dag_valid(klass, dag: nil)
       discrepancies = klass.dag(dag).validate
 

data/lib/dag_me/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DagMe
-  VERSION = '0.4.2'
+  VERSION = '0.5.0'
 end

data/lib/generators/dag_me/refresh_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+module DagMe
+  module Generators
+    # rails generate dag_me:refresh Task
+    #
+    # Upgrades an installed graph's function bodies to the current
+    # DagMe::DDL::REVISION. Named after the revision, so later refreshes
+    # get their own migration.
+    class RefreshGenerator < Rails::Generators::NamedBase
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      def create_migration_file
+        migration_template 'refresh_dag.rb.erb',
+                           "db/migrate/refresh_dag_me_r#{revision}_for_#{file_name.pluralize}.rb"
+      end
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      private
+
+      def revision
+        DagMe::DDL::REVISION
+      end
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/dag_me/templates/refresh_dag.rb.erb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class RefreshDagMeR<%= revision %>For<%= class_name.pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  # Replaces dag_me's function bodies with revision <%= revision %>.
+  # Tables, triggers, and rows are left alone.
+  def up
+    DagMe::DDL.refresh!(<%= class_name %>)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dag_me
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -46,6 +46,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - MIT-LICENSE
 - README.md
 - lib/dag_me.rb
@@ -64,7 +65,9 @@ files:
 - lib/dag_me/test_helper.rb
 - lib/dag_me/version.rb
 - lib/generators/dag_me/migration_generator.rb
+- lib/generators/dag_me/refresh_generator.rb
 - lib/generators/dag_me/templates/install_dag.rb.erb
+- lib/generators/dag_me/templates/refresh_dag.rb.erb
 homepage: https://github.com/ClosureTree/dag_me
 licenses:
 - MIT
@@ -87,7 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Multi-parent DAGs for ActiveRecord, powered by PostgreSQL 18+
 test_files: []