jekyll-relationships 0.1.0.alpha → 0.2.0.alpha

data/lib/jekyll-relationships/engine.rb

@@ -3,6 +3,8 @@
 require 'jekyll-relationships/engine/session'
 require 'jekyll-relationships/engine/raw_path_state'
 require 'jekyll-relationships/engine/relationship_state'
+require 'jekyll-relationships/engine/normal_seed'
+require 'jekyll-relationships/engine/persisted_links'
 require 'jekyll-relationships/engine/write_back'
 require 'jekyll-relationships/trees/graph'
 
@@ -27,7 +29,9 @@ class Engine
 		@configuration = Configuration.new(@site.config)
 		return unless @configuration.enabled?
 
-		@debug_logger = DebugLogger.new
+		@debug_logger = DebugLogger.new(
+			reference_key_property: @configuration.reference_template.key_property
+		)
 		@run_logger = RunLogger.new
 		@registry = Documents::Registry.new(site: @site, collections: @configuration.collections)
 		@data_path = Jekyll::Plugins::Relationships::Support::DataPath.new
@@ -39,33 +43,33 @@ class Engine
 		return if @configuration.collections.empty?
 
 		@registry.validate_collections!
-		@registry.validate_primary_paths!(primary_paths: @configuration.primary_paths)
-		original_tree_graph = build_tree_graph(active_document_ids: all_active_document_ids)
-		tree_provenance = Pruning::TreeProvenance.new(tree_graph: original_tree_graph)
-		prune_result = prune_result_for(
-			tree_provenance: tree_provenance,
-			original_tree_graph: original_tree_graph
-		)
-		final_session = Session.new(
-			engine: self,
-			active_document_ids: prune_result.fetch(:active_document_ids),
-			tree_graph: prune_result.fetch(:tree_graph)
+		@registry.validate_identity_schemes!(identity_schemes: @configuration.identity_schemes)
+		initial_active_document_ids = all_active_document_ids
+		initial_tree_seed_graph = build_tree_graph(active_document_ids: initial_active_document_ids)
+		normal_seed = NormalSeed.new(engine: self, active_document_ids: initial_active_document_ids)
+		persisted_links = PersistedLinks.new(engine: self)
+		final_result = final_result_for(
+			initial_active_document_ids: initial_active_document_ids,
+			initial_tree_seed_graph: initial_tree_seed_graph,
+			normal_seed: normal_seed,
+			persisted_links: persisted_links
 		)
-		final_session.resolve_all_relationships!
+		final_session = final_result.fetch(:session)
+		final_tree_graph = final_result.fetch(:tree_graph)
 		final_normal_graph = Pruning::NormalGraph.new(session: final_session)
 
 		log_relationship_summary(
 			session: final_session,
 			normal_graph: final_normal_graph,
-			tree_graph: prune_result.fetch(:tree_graph)
+			tree_graph: final_tree_graph
 		)
 		@run_logger.pruning_summary(
-			removed_documents_by_collection: removed_documents_by_collection(prune_result.fetch(:removed_documents))
+			removed_documents_by_collection: removed_documents_by_collection(final_result.fetch(:removed_documents))
 		) if @configuration.pruning_enabled?
 
 		final_session.write_back!
-		prune_result.fetch(:tree_graph).write_back!
-		remove_inactive_documents!(active_document_ids: prune_result.fetch(:active_document_ids))
+		final_tree_graph.write_back!
+		remove_inactive_documents!(active_document_ids: final_result.fetch(:active_document_ids))
 		@run_logger.finish!
 	end
 
@@ -92,31 +96,55 @@ class Engine
 		tree_graph
 	end
 
-	# Runs the configured prune rounds and returns the final active document set.
-	def prune_result_for(tree_provenance:, original_tree_graph:)
-		current_active_document_ids = all_active_document_ids
+	# Returns the final active graphs, either directly or via prune iteration.
+	def final_result_for(initial_active_document_ids:, initial_tree_seed_graph:, normal_seed:, persisted_links:)
+		return resolved_result_for(
+			active_document_ids: initial_active_document_ids,
+			tree_graph: initial_tree_seed_graph.deep_dup,
+			normal_seed: normal_seed,
+			persisted_links: persisted_links,
+			removed_documents: []
+		) unless @configuration.pruning_enabled?
+
+		prune_result_for(
+			initial_active_document_ids: initial_active_document_ids,
+			initial_tree_seed_graph: initial_tree_seed_graph,
+			normal_seed: normal_seed,
+			persisted_links: persisted_links
+		)
+	end
+
+	# Runs the configured prune rounds and returns the final active graphs.
+	def prune_result_for(initial_active_document_ids:, initial_tree_seed_graph:, normal_seed:, persisted_links:)
+		tree_phase = Pruning::TreePhase.new(
+			engine: self,
+			provenance: Pruning::TreeProvenance.new(tree_graph: initial_tree_seed_graph)
+		)
+		current_active_document_ids = initial_active_document_ids.dup
+		current_tree_seed_graph = initial_tree_seed_graph
 		removed_documents = {}
-		current_tree_graph = original_tree_graph
-		return {
-			active_document_ids: current_active_document_ids,
-			removed_documents: [],
-			tree_graph: current_tree_graph
-		} unless @configuration.pruning_enabled?
 
-		tree_phase = Pruning::TreePhase.new(engine: self, provenance: tree_provenance)
 		@configuration.prune_settings.prune_rounds.times do
-			tree_phase_result = tree_phase.process(active_document_ids: current_active_document_ids)
+			tree_phase_result = tree_phase.process(seed_graph: current_tree_seed_graph)
+			tree_seed_update = apply_removed_documents_to_seeds!(
+				tree_phase: tree_phase,
+				tree_seed_graph: current_tree_seed_graph,
+				normal_seed: normal_seed,
+				persisted_links: persisted_links,
+				current_active_document_ids: current_active_document_ids,
+				documents: tree_phase_result.fetch(:removed_documents)
+			)
+			current_tree_seed_graph = tree_seed_update.fetch(:tree_seed_graph)
 			register_removed_documents!(
 				removed_documents: removed_documents,
-				documents: tree_phase_result.fetch(:removed_documents)
+				documents: tree_seed_update.fetch(:removed_documents)
 			)
-			current_active_document_ids = tree_phase_result.fetch(:active_document_ids)
-			current_tree_graph = tree_phase_result.fetch(:tree_graph)
 
-			session = Session.new(
-				engine: self,
+			session = build_session(
 				active_document_ids: current_active_document_ids,
-				tree_graph: current_tree_graph
+				tree_graph: tree_phase_result.fetch(:graph),
+				normal_seed: normal_seed,
+				persisted_links: persisted_links
 			)
 			session.resolve_all_relationships!
 
@@ -124,35 +152,122 @@ class Engine
 				graph: Pruning::NormalGraph.new(session: session),
 				rules: @configuration.normal_prune_rules
 			).prune!
-			if normal_removed_documents.empty?
+			if normal_removed_documents.empty? && !tree_seed_changes_require_iteration?(tree_seed_update)
 				return {
 					active_document_ids: current_active_document_ids,
 					removed_documents: removed_documents.values,
-					tree_graph: current_tree_graph
+					tree_graph: tree_phase_result.fetch(:graph),
+					session: session
 				}
 			end
 
-			register_removed_documents!(
-				removed_documents: removed_documents,
+			normal_seed_update = apply_removed_documents_to_seeds!(
+				tree_phase: tree_phase,
+				tree_seed_graph: current_tree_seed_graph,
+				normal_seed: normal_seed,
+				persisted_links: persisted_links,
+				current_active_document_ids: current_active_document_ids,
 				documents: normal_removed_documents
 			)
-			current_active_document_ids -= normal_removed_documents.map(&:object_id)
-			post_normal_tree_phase = tree_phase.process(active_document_ids: current_active_document_ids)
+			current_tree_seed_graph = normal_seed_update.fetch(:tree_seed_graph)
 			register_removed_documents!(
 				removed_documents: removed_documents,
-				documents: post_normal_tree_phase.fetch(:removed_documents)
+				documents: normal_seed_update.fetch(:removed_documents)
 			)
-			current_active_document_ids = post_normal_tree_phase.fetch(:active_document_ids)
-			current_tree_graph = post_normal_tree_phase.fetch(:tree_graph)
 		end
 
-		{
+		resolved_result_for(
 			active_document_ids: current_active_document_ids,
-			removed_documents: removed_documents.values,
-			tree_graph: current_tree_graph
+			tree_graph: current_tree_seed_graph.deep_dup,
+			normal_seed: normal_seed,
+			persisted_links: persisted_links,
+			removed_documents: removed_documents.values
+		)
+	end
+
+	# Builds one final resolved session for the currently surviving seeds.
+	def resolved_result_for(active_document_ids:, tree_graph:, normal_seed:, persisted_links:, removed_documents:)
+		session = build_session(
+			active_document_ids: active_document_ids,
+			tree_graph: tree_graph,
+			normal_seed: normal_seed,
+			persisted_links: persisted_links
+		)
+		session.resolve_all_relationships!
+		{
+			active_document_ids: active_document_ids,
+			removed_documents: removed_documents,
+			tree_graph: tree_graph,
+			session: session
+		}
+	end
+
+	# Builds one normal-resolution session for one active graph snapshot.
+	def build_session(active_document_ids:, tree_graph:, normal_seed:, persisted_links:)
+		Session.new(
+			engine: self,
+			active_document_ids: active_document_ids,
+			tree_graph: tree_graph,
+			normal_seed: normal_seed,
+			persisted_links: persisted_links
+		)
+	end
+
+	# Applies removals to both seeds and returns the updated tree seed graph.
+	def apply_removed_documents_to_seeds!(tree_phase:, tree_seed_graph:, normal_seed:, persisted_links:, current_active_document_ids:, documents:)
+		requested_removed_documents = unique_documents(documents)
+		remove_from_normal_side!(
+			normal_seed: normal_seed,
+			persisted_links: persisted_links,
+			current_active_document_ids: current_active_document_ids,
+			documents: requested_removed_documents
+		)
+		tree_seed_result = tree_phase.apply_seed_removals(
+			seed_graph: tree_seed_graph,
+			documents: requested_removed_documents
+		)
+		extra_tree_removed_documents = unique_documents(
+			tree_seed_result.fetch(:removed_documents).reject do |document|
+				requested_removed_documents.any? { |requested_document| requested_document.object_id == document.object_id }
+			end
+		)
+		remove_from_normal_side!(
+			normal_seed: normal_seed,
+			persisted_links: persisted_links,
+			current_active_document_ids: current_active_document_ids,
+			documents: extra_tree_removed_documents
+		)
+
+		{
+			tree_seed_graph: tree_seed_result.fetch(:seed_graph),
+			removed_documents: unique_documents(requested_removed_documents + tree_seed_result.fetch(:removed_documents)),
+			seed_changed: tree_seed_result.fetch(:seed_changed)
 		}
 	end
 
+	# Removes documents from the normal seed, persisted overlay, and active set.
+	def remove_from_normal_side!(normal_seed:, persisted_links:, current_active_document_ids:, documents:)
+		documents = unique_documents(documents)
+		return if documents.empty?
+
+		normal_seed.remove_documents!(documents)
+		persisted_links.remove_documents!(documents)
+		documents.each do |document|
+			current_active_document_ids.delete(document.object_id)
+		end
+	end
+
+	# Returns true when tree-seed changes should schedule another outer round.
+	#
+	# Tree resolvers do not yet exist, so tree pruning can settle and flow
+	# directly into the same round's normal phase. When tree resolvers are added
+	# later, changing the seed here should trigger another full outer rebuild.
+	def tree_seed_changes_require_iteration?(tree_seed_update)
+		return false unless tree_seed_update.fetch(:seed_changed)
+
+		false
+	end
+
 	# Groups removed documents by collection label for summary logging.
 	def removed_documents_by_collection(documents)
 		Array(documents).each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |document, grouped_documents|
@@ -167,6 +282,13 @@ class Engine
 		end
 	end
 
+	# Returns one document array with later duplicates removed by object id.
+	def unique_documents(documents)
+		Array(documents).each_with_object({}) do |document, unique_documents|
+			unique_documents[document.object_id] ||= document
+		end.values
+	end
+
 	# Logs the configured relationship summary for the final active graph.
 	def log_relationship_summary(session:, normal_graph:, tree_graph:)
 		tree_graph_view = Pruning::TreePhase::TreeGraphView.new(tree_graph: tree_graph)

data/lib/jekyll-relationships/pruning/rule_pruner.rb

@@ -6,12 +6,11 @@ module Plugins
 module Relationships
 module Pruning
 
-# Applies minimum-count prune rules to a mutable graph view.
+# Applies configured prune-rule predicates to a mutable graph view.
 #
 # The graph view may represent either resolved normal relationships or the
-# current tree adjacency. Pruning is recursive within the supplied graph:
-# removing one document can reduce the neighbour counts of others, so the pruner
-# keeps deleting documents until every rule is satisfied.
+# current tree adjacency. Pruning is recursive within the supplied graph because
+# removing one document can make relationship predicates select others.
 class RulePruner
 	# Builds one pruner over one mutable graph view and one ordered rule list.
 	def initialize(graph:, rules:, subject_documents_resolver: nil)
@@ -20,7 +19,7 @@ class RulePruner
 		@subject_documents_resolver = subject_documents_resolver
 	end
 
-	# Removes documents until all configured minimums are satisfied.
+	# Removes documents until no configured rule selects another candidate.
 	def prune!
 		removed_documents = []
 
@@ -40,12 +39,13 @@ class RulePruner
 
 	private
 
-	# Finds every document that currently violates at least one prune rule.
+	# Finds every document selected by at least one prune rule.
 	def prune_candidates
 		@rules.each_with_object({}) do |rule, candidates|
 			subject_documents_for(rule).each do |document|
 				next if candidates.key?(document.object_id)
-				next unless rule.neighbour_documents(graph: @graph, document: document).length < rule.min
+				next unless rule.frontmatter_selected?(document)
+				next unless rule.relationship_selected?(graph: @graph, document: document)
 
 				candidates[document.object_id] = document
 			end

data/lib/jekyll-relationships/pruning/tree_phase.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'jekyll-relationships/trees/root_distances'
+
 module Jekyll
 module Plugins
 
@@ -21,6 +23,7 @@ class TreePhase
 			@documents_by_collection = Hash.new { |hash, key| hash[key] = {} }
 			@parents = Hash.new { |hash, key| hash[key] = {} }
 			@children = Hash.new { |hash, key| hash[key] = {} }
+			@root_distance_cache = nil
 			register_documents!
 			register_edges!
 		end
@@ -30,6 +33,32 @@ class TreePhase
 			@documents_by_collection[collection].values
 		end
 
+		# Returns every currently active tree document.
+		def tree_documents
+			@documents_by_collection.values.flat_map(&:values)
+		end
+
+		# Returns the direct parent documents for one active document.
+		def parent_documents_for(document)
+			return [] unless active_document?(document)
+
+			@parents[document].keys
+		end
+
+		# Returns the direct child documents for one active document.
+		def child_documents_for(document)
+			return [] unless active_document?(document)
+
+			@children[document].keys
+		end
+
+		# Returns the shortest current distance from one document to any root.
+		def root_distance_for(document)
+			return nil unless active_document?(document)
+
+			root_distances_for_graph[document.object_id]
+		end
+
 		# Returns the relevant neighbour documents for one configured tree member.
 		def neighbour_documents_for_member(member:, document:, inverse:)
 			return inverse_neighbours_for(member: member, document: document) if inverse
@@ -49,6 +78,7 @@ class TreePhase
 			end
 			@children.delete(document)
 			@parents.delete(document)
+			clear_root_distance_cache
 			true
 		end
 
@@ -116,6 +146,21 @@ class TreePhase
 				combined[document.object_id] ||= document
 			end.values
 		end
+
+		# Returns true when one document is still active in the mutable view.
+		def active_document?(document)
+			@documents_by_collection[document.collection.label].key?(document.object_id)
+		end
+
+		# Calculates the current root distances and caches them until the view changes.
+		def root_distances_for_graph
+			@root_distance_cache ||= Trees::RootDistances.for(graph: self)
+		end
+
+		# Clears the cached root distances after a structural tree change.
+		def clear_root_distance_cache
+			@root_distance_cache = nil
+		end
 	end
 
 	# Builds one tree phase helper for one engine and one immutable provenance set.
@@ -125,134 +170,88 @@ class TreePhase
 		@provenance = provenance
 	end
 
-	# Builds the pruned tree graph for one active document set.
-	def process(active_document_ids:)
-		current_active_document_ids = active_document_ids.dup
+	# Resolves tree pruning against one concrete tree seed graph.
+	def process(seed_graph:)
+		current_tree_graph = seed_graph.deep_dup
 		removed_documents = []
-		@current_active_document_ids = active_document_lookup(current_active_document_ids)
-		orphan_result = stabilise_orphans!(
-			current_active_document_ids: current_active_document_ids,
-			removed_documents: removed_documents
-		)
-		current_tree_graph = orphan_result.fetch(:graph)
+		stabilise_orphans!(graph: current_tree_graph, removed_documents: removed_documents)
 		return {
-			tree_graph: current_tree_graph,
-			active_document_ids: current_active_document_ids,
-			removed_documents: removed_documents
+			graph: current_tree_graph,
+			removed_documents: unique_documents(removed_documents)
 		} if @configuration.tree_prune_rules.empty?
 
-		eligible_document_ids_by_rule = eligible_document_ids_by_rule(graph: current_tree_graph)
-
 		loop do
-			pruned_documents = prune_tree_rules(
-				graph: current_tree_graph,
-				eligible_document_ids_by_rule: eligible_document_ids_by_rule
-			)
+			pruned_documents = prune_tree_rules(graph: current_tree_graph)
 			if pruned_documents.empty?
 				return {
-					tree_graph: current_tree_graph,
-					active_document_ids: current_active_document_ids,
-					removed_documents: removed_documents
+					graph: current_tree_graph,
+					removed_documents: unique_documents(removed_documents)
 				}
 			end
 
-			remove_documents!(
-				current_active_document_ids: current_active_document_ids,
-				documents: pruned_documents
-			)
+			current_tree_graph.remove_documents!(pruned_documents)
 			removed_documents.concat(pruned_documents)
-			current_tree_graph = stabilise_orphans!(
-				current_active_document_ids: current_active_document_ids,
-				removed_documents: removed_documents
-			).fetch(:graph)
+			stabilise_orphans!(graph: current_tree_graph, removed_documents: removed_documents)
+		end
+	end
+
+	# Applies committed removals to one tree seed graph and repairs the tree.
+	#
+	# The tree seed only changes because documents have permanently died. Resolver
+	# output never flows back into the seed, but structural repair such as orphan
+	# reattachment must be reflected so the next round starts from the right tree.
+	def apply_seed_removals(seed_graph:, documents:)
+		documents_to_remove = Array(documents).select do |document|
+			seed_graph.participating?(document) && seed_graph.active_document?(document)
+		end
+		return {
+			seed_graph: seed_graph,
+			removed_documents: [],
+			seed_changed: false
+		} if documents_to_remove.empty?
+
+		next_seed_graph = seed_graph.deep_dup
+		removed_documents = documents_to_remove.select do |document|
+			next_seed_graph.remove_document!(document)
 		end
+		stabilise_orphans!(graph: next_seed_graph, removed_documents: removed_documents)
+
+		{
+			seed_graph: next_seed_graph,
+			removed_documents: unique_documents(removed_documents),
+			seed_changed: removed_documents.any?
+		}
 	end
 
 	private
 
-	# Rebuilds the tree graph until orphan handling no longer removes documents.
-	def stabilise_orphans!(current_active_document_ids:, removed_documents:)
+	# Removes or reattaches orphans until the graph stabilises.
+	def stabilise_orphans!(graph:, removed_documents:)
 		loop do
-			@current_active_document_ids = active_document_lookup(current_active_document_ids)
-			base_graph = build_tree_graph(active_document_ids: current_active_document_ids)
-			orphan_result = apply_orphan_policy(graph: base_graph)
+			orphan_result = apply_orphan_policy(graph: graph)
 			orphaned_documents = orphan_result.fetch(:removed_documents)
-			return {
-				graph: orphan_result.fetch(:graph)
-			} if orphaned_documents.empty?
+			return graph if orphaned_documents.empty?
 
-			remove_documents!(
-				current_active_document_ids: current_active_document_ids,
-				documents: orphaned_documents
-			)
+			graph.remove_documents!(orphaned_documents)
 			removed_documents.concat(orphaned_documents)
 		end
 	end
 
-	# Builds one fresh tree graph for the current active document set.
-	def build_tree_graph(active_document_ids:)
-		tree_graph = Trees::Graph.new(
-			site: @engine.site,
-			configuration: @configuration,
-			registry: @engine.registry,
-			data_path: @engine.data_path,
-			debug_logger: @engine.debug_logger,
-			active_document_ids: active_document_ids
-		)
-		tree_graph.build!
-		tree_graph
-	end
-
-	# Builds one stable lookup of which documents each tree rule may prune.
-	def eligible_document_ids_by_rule(graph:)
-		root_distances = root_distances_for(graph)
-		@configuration.tree_prune_rules.each_with_object({}) do |rule, lookup|
-			lookup[rule.object_id] = graph.documents_for(rule.subject_collection).each_with_object({}) do |document, eligible_documents|
-				next unless depth_selected?(depth: rule.depth, root_distance: root_distances[document.object_id])
-
-				eligible_documents[document.object_id] = true
-			end
-		end
-	end
-
-	# Runs the configured tree prune rules against the current graph while only
-	# allowing the documents selected by the initial depth snapshot to be pruned.
-	def prune_tree_rules(graph:, eligible_document_ids_by_rule:)
+	# Runs the configured tree prune rules against the current graph, re-reading
+	# depth from the mutable graph view each time candidates are evaluated.
+	def prune_tree_rules(graph:)
 		RulePruner.new(
 			graph: TreeGraphView.new(tree_graph: graph),
 			rules: @configuration.tree_prune_rules,
 			subject_documents_resolver: lambda do |rule, mutable_graph|
-				eligible_document_ids = eligible_document_ids_by_rule.fetch(rule.object_id)
 				mutable_graph.documents_for(rule.subject_collection).select do |document|
-					eligible_document_ids.key?(document.object_id)
+					depth = rule.depth
+					depth.nil? || depth_selected?(depth: depth, root_distance: mutable_graph.root_distance_for(document))
 				end
 			end
 		).prune!
 	end
 
-	# Calculates the shortest distance from every node to any root in the current tree.
-	def root_distances_for(graph)
-		root_distances = {}
-		queue = graph.tree_documents.select do |document|
-			graph.parent_documents_for(document).empty?
-		end.sort_by(&:relative_path).map do |root_document|
-			[root_document, 0]
-		end
-
-		until queue.empty?
-			document, distance = queue.shift
-			existing_distance = root_distances[document.object_id]
-			next if !existing_distance.nil? && existing_distance <= distance
-
-			root_distances[document.object_id] = distance
-			graph.child_documents_for(document).each do |child_document|
-				queue << [child_document, distance + 1]
-			end
-		end
-
-		root_distances
-	end
-
 	# Returns true when one root distance is eligible under one configured depth.
 	def depth_selected?(depth:, root_distance:)
 		return false if root_distance.nil?
@@ -264,21 +263,6 @@ class TreePhase
 		end
 	end
 
-	# Removes many documents from the current active set in place.
-	def remove_documents!(current_active_document_ids:, documents:)
-		Array(documents).each do |document|
-			current_active_document_ids.delete(document.object_id)
-			@current_active_document_ids.delete(document.object_id)
-		end
-	end
-
-	# Builds one fast active-document lookup for the current build state.
-	def active_document_lookup(active_document_ids)
-		active_document_ids.each_with_object({}) do |document_id, active_ids|
-			active_ids[document_id] = true
-		end
-	end
-
 	# Applies the configured orphan policy to one current tree graph.
 	def apply_orphan_policy(graph:)
 		removed_documents = []
@@ -307,30 +291,31 @@ class TreePhase
 		end.sort_by(&:relative_path)
 	end
 
-	# Attempts to reconnect one orphan to its surviving original grandparents.
+	# Attempts to reconnect one orphan to its nearest surviving original ancestors.
 	def reattach_orphan!(graph:, document:)
-		grandparent_candidates_for(document).each do |candidate|
+		nearest_surviving_ancestor_candidates_for(graph: graph, document: document).each do |candidate|
 			graph.add_edge(
 				parent_document: candidate.fetch(:document),
 				child_document: document,
 				tree_settings: candidate.fetch(:tree_settings),
 				definition: candidate.fetch(:definition),
-				source_description: 'pruning grandparents'
+				source_description: 'pruning ancestors'
 			)
 		end
 
 		graph.parent_documents_for(document).any?
 	end
 
-	# Returns every surviving grandparent candidate for one orphan.
-	def grandparent_candidates_for(document)
+	# Returns the first surviving ancestor on every original parent lineage.
+	def nearest_surviving_ancestor_candidates_for(graph:, document:)
 		@provenance.original_parent_entries_for(document).each_with_object({}) do |parent_entry, candidates|
-			@provenance.original_parent_entries_for(parent_entry.fetch(:document)).each do |grandparent_entry|
-				grandparent_document = grandparent_entry.fetch(:document)
-				next unless current_document?(grandparent_document)
-
-				candidates[grandparent_document.object_id] ||= {
-					document: grandparent_document,
+			nearest_surviving_ancestors_for(
+				graph: graph,
+				document: parent_entry.fetch(:document),
+				visited_document_ids: {}
+			).each do |ancestor_document|
+				candidates[ancestor_document.object_id] ||= {
+					document: ancestor_document,
 					definition: parent_entry.fetch(:definition),
 					tree_settings: parent_entry.fetch(:tree_settings)
 				}
@@ -338,9 +323,28 @@ class TreePhase
 		end.values
 	end
 
-	# Returns true when one document is still active in the current build.
-	def current_document?(document)
-		@current_active_document_ids.key?(document.object_id)
+	# Walks removed provenance nodes until each lineage reaches an active document.
+	def nearest_surviving_ancestors_for(graph:, document:, visited_document_ids:)
+		return [] if visited_document_ids.key?(document.object_id)
+		return [document] if graph.active_document?(document)
+
+		lineage_visited_document_ids = visited_document_ids.merge(document.object_id => true)
+		@provenance.original_parent_entries_for(document).each_with_object({}) do |parent_entry, ancestors|
+			nearest_surviving_ancestors_for(
+				graph: graph,
+				document: parent_entry.fetch(:document),
+				visited_document_ids: lineage_visited_document_ids
+			).each do |ancestor_document|
+				ancestors[ancestor_document.object_id] ||= ancestor_document
+			end
+		end.values
+	end
+
+	# Returns one document array with later duplicates removed by object id.
+	def unique_documents(documents)
+		Array(documents).each_with_object({}) do |document, unique_documents|
+			unique_documents[document.object_id] ||= document
+		end.values
 	end
 end