jekyll-relationships 0.1.1.alpha → 0.2.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4f49c60e8c57f7661b7fdec54b0d4d8ce2e9564dca858e86126ed2f810bfdec
-  data.tar.gz: f0c22961ff04cc0493e923676d45a9de3c69ff6720f72160e7897bf921272687
+  metadata.gz: 583920383adff1b25fb21db2130a379a76c6070780bb6fceddeb04c8eb0c5340
+  data.tar.gz: 528d4185f7ee05eced524a732096f19eea13750cb2ca85efa0d9cf325ad532dd
 SHA512:
-  metadata.gz: d4b352ce61991bf340b239a9aa881e1314274371637a96e24f317597a6343fb5bebb763fbe6b60f31d8877b3e01f1e4bfc5076994382940f08a757906f632933
-  data.tar.gz: 1ec40c78e1bf65e5781b580c4effc37e5510424031267c120a08be6bb6a0c5ffc1f36ccffa1fc4817b6c1ddc451fe996947b4403af48e36db7112d875dcd0bc2
+  metadata.gz: ede20ebf3d937fa6deda8da76f087d4040f7de50204b70675646cfcc3b860014d69929afde3de3c1f243cf8810f31a723ab914373ca8120a68308d6852501b9e
+  data.tar.gz: 3a5a9f5b7d9ed651af6bd9485749d6b0cf37d366f4da3a238d05c4f533440374bbc27dcfd3b43643d62c91a2a80646037130a296ecf86b3c59f3c8d38303e958

data/lib/jekyll-relationships/configuration/defaults.rb

@@ -15,6 +15,7 @@ class Configuration
 		FRONTMATTER = {
 			'base' => 'relationships',
 			'primary' => nil,
+			'scope' => nil,
 			'foreign' => '<collection>',
 			'output' => nil
 		}.freeze

data/lib/jekyll-relationships/configuration/frontmatter.rb

@@ -9,9 +9,17 @@ class Configuration
 
 	# Encapsulates one merged frontmatter configuration block.
 	#
-	# Instances resolve `base`, `primary`, `foreign`, and `output` paths so the
+	# Instances resolve `base`, `primary`, `scope`, `foreign`, and `output` paths so the
 	# rest of the engine can work with explicit values only.
 	class Frontmatter
+		# Describes one configured scope field while preserving both its public name and its base-resolved document path.
+		ScopeField = Struct.new(:name, :path) do
+			# Returns a stable value signature suitable for registry cache keys.
+			def signature
+				[name, path]
+			end
+		end
+
 		# Builds one frontmatter configuration helper.
 		def initialize(raw_config:, string_array:)
 			@raw_config = raw_config.is_a?(Hash) ? raw_config : {}
@@ -34,6 +42,25 @@ class Configuration
 			apply_base(raw_primary.to_s)
 		end
 
+		# Returns the configured scope fields with their literal reference keys and resolved document paths.
+		def scope_fields
+			raw_scope = fetch_value('scope')
+			return [] if raw_scope.nil?
+			unless raw_scope.is_a?(String) || raw_scope.is_a?(Array)
+				raise ConfigurationError, '`frontmatter.scope` must be a string, comma-delimited string, or array of non-empty path strings.'
+			end
+
+			raw_paths = raw_scope.is_a?(String) ? @string_array.interpret(raw_scope, split: true, flatten: true) : raw_scope
+			if raw_paths.empty? || raw_paths.any? { |path| !path.is_a?(String) || path.strip.empty? }
+				raise ConfigurationError, '`frontmatter.scope` must contain one or more non-empty path strings.'
+			end
+
+			raw_paths.map do |path|
+				name = path.strip
+				ScopeField.new(name, apply_base(name)).freeze
+			end.uniq { |field| field.name }
+		end
+
 		# Returns the resolved foreign input paths for one target collection.
 		def foreign_paths_for(to_collection:)
 			raw_foreign = fetch_value('foreign')

data/lib/jekyll-relationships/configuration/parser.rb

@@ -241,6 +241,7 @@ class Configuration
 				from_collection: from_collection,
 				to_collection: to_collection,
 				primary_path: frontmatter.primary_path,
+				scope_fields: frontmatter.scope_fields,
 				parent_child_pairs: parent_child_pairs(from_collection: from_collection, to_collection: to_collection, mode: mode),
 				tree_settings: tree_settings,
 				debug: debug,
@@ -259,6 +260,7 @@ class Configuration
 				from_collection: from_collection,
 				to_collection: to_collection,
 				primary_path: frontmatter.primary_path,
+				scope_fields: frontmatter.scope_fields,
 				foreign_paths: frontmatter.foreign_paths_for(to_collection: to_collection),
 				output_path: frontmatter.output_path_for(to_collection: to_collection),
 				debug: debug,
@@ -291,11 +293,25 @@ class Configuration
 				if prune_configuration.shortcut?
 					raise ConfigurationError, "Relationship entry #{entry_index + 1} cannot use `prune: <int>` on a tree relationship."
 				end
-				if prune_configuration.depth.nil?
+				if prune_configuration.min && prune_configuration.depth.nil?
 					raise ConfigurationError, "Relationship entry #{entry_index + 1} must define `prune.depth` when pruning a tree relationship."
 				end
-			elsif !prune_configuration.depth.nil?
-				raise ConfigurationError, "Relationship entry #{entry_index + 1} cannot define `prune.depth` on a normal relationship."
+				if prune_configuration.min.nil? && prune_configuration.depth
+					raise ConfigurationError, "Relationship entry #{entry_index + 1} must define `prune.min` when defining `prune.depth` on a tree relationship."
+				end
+				if prune_configuration.min.nil? && prune_configuration.where.nil?
+					raise ConfigurationError, "Relationship entry #{entry_index + 1} must define either `prune.where` or both `prune.min` and `prune.depth` when pruning a tree relationship."
+				end
+			else
+				if prune_configuration.where
+					raise ConfigurationError, "Relationship entry #{entry_index + 1} cannot define `prune.where` on a normal relationship."
+				end
+				if !prune_configuration.depth.nil?
+					raise ConfigurationError, "Relationship entry #{entry_index + 1} cannot define `prune.depth` on a normal relationship."
+				end
+				if prune_configuration.min.nil?
+					raise ConfigurationError, "Relationship entry #{entry_index + 1} must define `prune.min` when pruning a normal relationship."
+				end
 			end
 
 			prune_rules_for_entry(
@@ -358,6 +374,7 @@ class Configuration
 				members: members,
 				min: prune_configuration.min,
 				depth: prune_configuration.depth,
+				where: prune_configuration.where,
 				inverse: prune_configuration.inverse?,
 				entry_index: entry_index
 			)

data/lib/jekyll-relationships/configuration/prune_rule_settings.rb

@@ -11,10 +11,10 @@ class Configuration
 	#
 	# Relationship entries and hash-form targets may opt into pruning by defining
 	# a minimum neighbour count and, optionally, switching the subject of the rule
-	# to the inverse side of the relationship. Tree prune rules may also
-	# constrain which depths are eligible for pruning.
+	# to the inverse side of the relationship. Tree prune rules may constrain
+	# eligible depths, select frontmatter values, or combine both modes.
 	class PruneRuleSettings
-		attr_reader :mode, :min, :depth
+		attr_reader :mode, :min, :depth, :where
 
 		# Interprets one loose prune config value.
 		def self.build(raw_config:, context:)
@@ -31,6 +31,7 @@ class Configuration
 				@mode = 'direct'
 				@min = normalise_min(raw_config, context: context)
 				@depth = nil
+				@where = nil
 				return
 			end
 
@@ -43,11 +44,15 @@ class Configuration
 			@min = normalise_min(
 				Configuration::HashUtilities.fetch_hash_value(raw_config, 'min'),
 				context: context
-			)
+			) if Configuration::HashUtilities.hash_key?(raw_config, 'min')
 			@depth = normalise_depth(
 				Configuration::HashUtilities.hash_key?(raw_config, 'depth') ? Configuration::HashUtilities.fetch_hash_value(raw_config, 'depth') : nil,
 				context: context
 			)
+			@where = normalise_where(
+				Configuration::HashUtilities.fetch_hash_value(raw_config, 'where'),
+				context: context
+			) if Configuration::HashUtilities.hash_key?(raw_config, 'where')
 		end
 
 		# Returns true when the rule prunes the inverse side of the relationship.
@@ -73,7 +78,7 @@ class Configuration
 			raise ConfigurationError, "Unsupported `#{context}.mode` value `#{raw_mode}`."
 		end
 
-		# Resolves the configured minimum count and rejects non-positive values.
+		# Resolves the configured minimum count and rejects missing or non-positive values.
 		def normalise_min(raw_min, context:)
 			raise ConfigurationError, "`#{context}` must define `min`." if raw_min.nil?
 
@@ -92,6 +97,29 @@ class Configuration
 
 			interpreted_depth
 		end
+
+		# Resolves a non-empty hash of valid dot paths to exact expected values.
+		def normalise_where(raw_where, context:)
+			raise ConfigurationError, "`#{context}.where` must be a non-empty hash." unless raw_where.is_a?(Hash) && !raw_where.empty?
+
+			raw_where.each_with_object({}) do |(raw_path, expected_value), where|
+				path = normalise_where_path(raw_path, context: context)
+				raise ConfigurationError, "`#{context}.where` defines path `#{path}` more than once." if where.key?(path)
+
+				where[path] = expected_value
+			end.freeze
+		end
+
+		# Resolves one dot path and rejects blank segments.
+		def normalise_where_path(raw_path, context:)
+			path = raw_path.to_s.strip
+			segments = path.split('.', -1).map(&:strip)
+			if path.empty? || segments.any?(&:empty?)
+				raise ConfigurationError, "`#{context}.where` paths must contain non-blank dot-separated fields."
+			end
+
+			segments.join('.')
+		end
 	end
 end
 

data/lib/jekyll-relationships/configuration.rb

@@ -53,10 +53,6 @@ class Configuration
 			),
 			string_array: @string_array
 		)
-		@reference_template = References::Template.new(
-			config: build_reference_config,
-			count_enabled: @multiple_settings.count?
-		)
 		@tree_settings = TreeSettings.defaults(
 			string_array: @string_array
 		).merge_level(
@@ -81,6 +77,11 @@ class Configuration
 		@configured_relationships = parsed_result.fetch(:configured_relationships)
 		@normal_prune_rules = parsed_result.fetch(:normal_prune_rules)
 		@tree_prune_rules = parsed_result.fetch(:tree_prune_rules)
+		@reference_template = References::Template.new(
+			config: build_reference_config(scope_enabled: scope_configured?),
+			count_enabled: @multiple_settings.count?
+		)
+		validate_scope_reference_template!
 		attach_resolvers!(parser: parsed_relationships)
 	end
 
@@ -119,6 +120,24 @@ class Configuration
 		(normal_paths + tree_paths).uniq
 	end
 
+	# Returns every distinct primary-key and scope scheme used by configured relationships.
+	def identity_schemes
+		definitions = @normal_relationships.values.flat_map(&:values) + @tree_relationships
+		definitions.group_by do |definition|
+			[
+				definition.primary_path,
+				definition.scope_fields.map(&:signature)
+			]
+		end.map do |_, matching_definitions|
+			{
+				primary_path: matching_definitions.first.primary_path,
+				scope_fields: matching_definitions.first.scope_fields,
+				collections: matching_definitions.flat_map { |definition| [definition.from_collection, definition.to_collection] }.uniq.sort,
+				relationships: matching_definitions.map { |definition| "#{definition.from_collection} -> #{definition.to_collection}" }.uniq
+			}
+		end
+	end
+
 	private
 
 	# Builds the active global enabled setting.
@@ -142,7 +161,7 @@ class Configuration
 			string_array: @string_array
 		)
 		@reference_template = References::Template.new(
-			config: default_reference_config,
+			config: default_reference_config(scope_enabled: false),
 			count_enabled: @multiple_settings.count?
 		)
 		@tree_settings = TreeSettings.defaults(string_array: @string_array)
@@ -195,8 +214,8 @@ class Configuration
 	end
 
 	# Builds the resolved reference template config.
-	def build_reference_config
-		default_references = default_reference_config
+	def build_reference_config(scope_enabled:)
+		default_references = default_reference_config(scope_enabled: scope_enabled)
 		explicit_config = Configuration::HashUtilities.fetch_hash_value(@raw_config, 'references')
 		return explicit_config if explicit_config.is_a?(Hash)
 
@@ -212,12 +231,15 @@ class Configuration
 	end
 
 	# Builds the default reference template shape for the active duplicate mode.
-	def default_reference_config
+	def default_reference_config(scope_enabled:)
 		default_references = {
 			'id' => Jekyll::Plugins::Relationships::Support::Placeholders::KEY,
 			'collection' => Jekyll::Plugins::Relationships::Support::Placeholders::COLLECTION,
 			'page' => Jekyll::Plugins::Relationships::Support::Placeholders::PAGE
 		}
+		if scope_enabled
+			default_references['scope'] = Jekyll::Plugins::Relationships::Support::Placeholders::SCOPE
+		end
 		if @multiple_settings.count?
 			default_references['count'] = Jekyll::Plugins::Relationships::Support::Placeholders::COUNT
 		end
@@ -225,6 +247,19 @@ class Configuration
 		default_references
 	end
 
+	# Returns true when at least one concrete relationship uses scoped identity.
+	def scope_configured?
+		identity_schemes.any? { |scheme| !scheme.fetch(:scope_fields).empty? }
+	end
+
+	# Ensures scoped relationships have a reserved location for their complete effective scope.
+	def validate_scope_reference_template!
+		return unless scope_configured?
+		return if @reference_template.scope_property
+
+		raise ConfigurationError, 'Reference config must define exactly one <scope> property when any relationship configures `frontmatter.scope`.'
+	end
+
 	# Attaches registered resolver classes to matching concrete relationships.
 	def attach_resolvers!(parser:)
 		Resolvers::Base.registered_subclasses.each do |resolver_class|

data/lib/jekyll-relationships/definitions/normal_relationship.rb

@@ -11,14 +11,15 @@ module Definitions
 # Each instance describes one source collection, one target collection, and the
 # resolved frontmatter rules that apply to links between them.
 class NormalRelationship
-	attr_reader :from_collection, :to_collection, :primary_path, :foreign_paths,
+	attr_reader :from_collection, :to_collection, :primary_path, :scope_fields, :foreign_paths,
 		:output_path, :sequence, :reads_frontmatter, :bidirectional, :resolver_classes
 
 	# Captures the resolved configuration for one concrete pair.
-	def initialize(from_collection:, to_collection:, primary_path:, foreign_paths:, output_path:, debug:, sequence:, reads_frontmatter:, bidirectional:)
+	def initialize(from_collection:, to_collection:, primary_path:, scope_fields: [], foreign_paths:, output_path:, debug:, sequence:, reads_frontmatter:, bidirectional:)
 		@from_collection = from_collection
 		@to_collection = to_collection
 		@primary_path = primary_path
+		@scope_fields = scope_fields.freeze
 		@foreign_paths = foreign_paths
 		@output_path = output_path
 		@debug = debug
@@ -38,6 +39,11 @@ class NormalRelationship
 		@debug.enabled?(area)
 	end
 
+	# Returns true when this relationship is the synthetic inverse of a bidirectional pair.
+	def bidirectional_mirror?
+		@bidirectional && !@reads_frontmatter
+	end
+
 	# Returns true when one event's related IDs satisfy this pair's debug filter.
 	def debug_ids_match?(ids)
 		@debug.matches_ids?(ids)

data/lib/jekyll-relationships/definitions/prune_rule.rb

@@ -11,17 +11,19 @@ module Definitions
 # Raw relationship entries may expand into many concrete relationship members.
 # After the global prune settings have been applied, each expanded prune rule
 # targets exactly one subject collection and one set of configured relationship
-# members whose neighbour counts should be combined for that subject.
+# members. Rules select by neighbour count, frontmatter values, or both.
 class PruneRule
-	attr_reader :kind, :subject_collection, :members, :min, :depth, :entry_index
+	attr_reader :kind, :subject_collection, :members, :min, :depth, :where, :entry_index
 
 	# Captures one immutable prune rule.
-	def initialize(kind:, subject_collection:, members:, min:, depth:, inverse:, entry_index:)
+	def initialize(kind:, subject_collection:, members:, min:, depth:, where:, inverse:, entry_index:)
 		@kind = kind
 		@subject_collection = subject_collection
 		@members = members.sort_by(&:sequence).freeze
 		@min = min
 		@depth = depth
+		@where = where
+		@frontmatter_matcher = Support::FrontmatterMatcher.new(expected_values: @where) unless @where.nil?
 		@inverse = inverse
 		@entry_index = entry_index
 	end
@@ -41,6 +43,20 @@ class PruneRule
 		@kind == :normal
 	end
 
+	# Returns true when the document satisfies this rule's frontmatter mode.
+	def frontmatter_selected?(document)
+		return true unless @frontmatter_matcher
+
+		@frontmatter_matcher.matches?(document.data)
+	end
+
+	# Returns true when the document satisfies this rule's relationship mode.
+	def relationship_selected?(graph:, document:)
+		return true if @min.nil?
+
+		neighbour_documents(graph: graph, document: document).length < @min
+	end
+
 	# Returns the combined neighbour documents for one subject document.
 	def neighbour_documents(graph:, document:)
 		@members.each_with_object({}) do |member, neighbours|

data/lib/jekyll-relationships/definitions/tree_relationship.rb

@@ -12,13 +12,14 @@ module Definitions
 # and which frontmatter, maximum, URL, and primary-key rules should be used to
 # resolve references for this concrete relationship definition.
 class TreeRelationship
-	attr_reader :from_collection, :to_collection, :primary_path, :tree_settings, :sequence
+	attr_reader :from_collection, :to_collection, :primary_path, :scope_fields, :tree_settings, :sequence
 
 	# Captures the allowed parent-child directions for one tree definition.
-	def initialize(from_collection:, to_collection:, primary_path:, parent_child_pairs:, tree_settings:, debug:, sequence:)
+	def initialize(from_collection:, to_collection:, primary_path:, scope_fields: [], parent_child_pairs:, tree_settings:, debug:, sequence:)
 		@from_collection = from_collection
 		@to_collection = to_collection
 		@primary_path = primary_path
+		@scope_fields = scope_fields.freeze
 		@parent_child_pairs = parent_child_pairs
 		@tree_settings = tree_settings
 		@debug = debug

data/lib/jekyll-relationships/documents/registry.rb

@@ -6,17 +6,18 @@ module Plugins
 module Relationships
 module Documents
 
-# Indexes participating documents by collection and primary key.
+# Indexes participating documents by collection, primary key, and optional complete scope.
 #
-# Indices are built lazily per primary-key path so relationship definitions can
-# use different key schemes without rebuilding unrelated lookups.
+# Indices are built lazily per complete identity scheme so relationship definitions can
+# use different primary and scope paths without rebuilding unrelated lookups.
 class Registry
 
 	# Builds the registry over the collections used by the configuration.
 	def initialize(site:, collections:)
 		@site = site
 		@collections = collections
-		@indices_by_primary_path = {}
+		@indices_by_identity = {}
+		@data_path = Jekyll::Plugins::Relationships::Support::DataPath.new
 	end
 
 	# Returns true when the document belongs to one of the tracked collections.
@@ -48,7 +49,19 @@ class Registry
 	# Builds every requested primary-key index so duplicates fail eagerly.
 	def validate_primary_paths!(primary_paths:)
 		Array(primary_paths).uniq.each do |primary_path|
-			index_for(primary_path)
+			index_for(primary_path: primary_path, scope_fields: [])
+		end
+	end
+
+	# Builds every requested identity index so missing scope values and duplicate identities fail eagerly.
+	def validate_identity_schemes!(identity_schemes:)
+		Array(identity_schemes).each do |scheme|
+			index_for(
+				primary_path: scheme.fetch(:primary_path),
+				scope_fields: scheme.fetch(:scope_fields),
+				collections: scheme.fetch(:collections),
+				relationship: scheme.fetch(:relationships).join(', ')
+			)
 		end
 	end
 
@@ -57,61 +70,157 @@ class Registry
 		if primary_path.nil?
 			default_relative_key(document)
 		else
-			value = Jekyll::Plugins::Relationships::Support::DataPath.new.read(document.data, primary_path)
+			value = @data_path.read(document.data, primary_path)
 			raise ResolutionError, "Document `#{document.relative_path}` is missing primary key path `#{primary_path}`." if value.nil?
 
 			value.to_s
 		end
 	end
 
-	# Resolves one key to a document, optionally constrained to a collection.
-	def lookup(key:, primary_path:, collection: nil)
-		index = index_for(primary_path)
-		if collection
-			document = fetch_nested(index.fetch(:by_collection), collection, key.to_s)
-			raise ResolutionError, "Could not resolve key `#{key}` in collection `#{collection}`." unless document
+	# Reads and validates a document's complete scope for one configured identity scheme.
+	def scope_for(document, scope_fields:, relationship: nil)
+		return nil if scope_fields.empty?
+
+		scope_fields.each_with_object({}) do |field, scope|
+			value = @data_path.read(document.data, field.path)
+			if value.nil?
+				raise ResolutionError, "#{relationship_prefix(relationship)}document `#{document.relative_path}` is missing required scope field `#{field.name}` at frontmatter path `#{field.path}`."
+			end
+
+			scope[field.name] = value
+		end
+	end
+
+	# Resolves reference overrides over the referring document's scope and validates every configured field.
+	def effective_scope_for(reference_scope:, referring_document:, scope_fields:, relationship: nil)
+		return nil if scope_fields.empty? && (reference_scope.nil? || reference_scope.empty?)
+
+		reference_scope ||= {}
+		unless reference_scope.is_a?(Hash)
+			raise ResolutionError, "#{relationship_prefix(relationship)}reference on document `#{referring_document.relative_path}` must provide scope as a hash."
+		end
+
+		configured_names = scope_fields.map(&:name)
+		unknown_names = reference_scope.keys.map(&:to_s) - configured_names
+		unless unknown_names.empty?
+			raise ResolutionError, "#{relationship_prefix(relationship)}reference on document `#{referring_document.relative_path}` uses unconfigured scope field `#{unknown_names.first}`."
+		end
+
+		scope_fields.each_with_object({}) do |field, effective_scope|
+			value = if hash_property?(reference_scope, field.name)
+						 Jekyll::Plugins::Relationships::Support::FrontmatterPath.read_hash(reference_scope, field.name)
+					 else
+						 @data_path.read(referring_document.data, field.path)
+					 end
+			if value.nil?
+				raise ResolutionError, "#{relationship_prefix(relationship)}reference on document `#{referring_document.relative_path}` has no effective value for scope field `#{field.name}`."
+			end
 
-			return document
+			effective_scope[field.name] = value
 		end
+	end
+
+	# Ensures one already-selected target contains and exactly matches an effective scope.
+	def validate_scope_match!(document:, scope:, scope_fields:, relationship: nil, referring_document: nil)
+		return nil if scope_fields.empty?
 
-		matches = index.fetch(:by_key).fetch(key.to_s, [])
-		raise ResolutionError, "Could not resolve key-only reference `#{key}`." if matches.empty?
-		return matches.first if index.fetch(:site_wide_unique)
-		return matches.first if matches.length == 1
+		target_scope = scope_for(document, scope_fields: scope_fields, relationship: relationship)
+		scope_fields.each do |field|
+			next if target_scope.fetch(field.name) == scope.fetch(field.name)
 
-		collections = matches.map { |document| collection_label(document) }.uniq.sort.join(', ')
-		raise ResolutionError, "Key-only reference `#{key}` is ambiguous across collections: #{collections}."
+			raise ResolutionError, scope_mismatch_message(
+				document: document,
+				field: field,
+				expected_value: scope.fetch(field.name),
+				actual_value: target_scope.fetch(field.name),
+				relationship: relationship,
+				referring_document: referring_document
+			)
+		end
+
+		target_scope
+	end
+
+	# Resolves one key and complete scope to a document, optionally constrained to a collection.
+	def lookup(key:, primary_path:, collection: nil, scope_fields: [], scope: nil, relationship: nil, referring_document: nil)
+		index = index_for(primary_path: primary_path, scope_fields: scope_fields, relationship: relationship)
+		candidates = if collection
+						 fetch_nested(index.fetch(:by_collection), collection, key.to_s) || []
+					 else
+						 index.fetch(:by_key).fetch(key.to_s, [])
+					 end
+		if candidates.empty?
+			if collection
+				raise ResolutionError, "#{relationship_prefix(relationship)}could not resolve key `#{key}` in collection `#{collection}`#{source_suffix(referring_document)}."
+			end
+
+			raise ResolutionError, "#{relationship_prefix(relationship)}could not resolve key-only reference `#{key}`#{source_suffix(referring_document)}."
+		end
+
+		matches = if scope_fields.empty?
+					 candidates
+				 else
+					 candidates.select { |entry| entry.fetch(:scope) == scope }
+				 end
+		if matches.empty?
+			raise_scope_mismatch!(
+				candidates: candidates,
+				scope: scope,
+				scope_fields: scope_fields,
+				relationship: relationship,
+				referring_document: referring_document
+			)
+		end
+
+		matched_documents = matches.map { |entry| entry.fetch(:document) }
+		return matched_documents.first if collection
+
+		return matched_documents.first if matched_documents.length == 1
+
+		collections = matched_documents.map { |document| collection_label(document) }.uniq.sort.join(', ')
+		raise ResolutionError, "#{relationship_prefix(relationship)}key-only reference `#{key}` is ambiguous across collections: #{collections}#{source_suffix(referring_document)}."
 	end
 
 	private
 
-	# Returns or builds the index for one primary-key scheme.
-	def index_for(primary_path)
-		signature = primary_path.nil? ? '__relative_path__' : primary_path
-		@indices_by_primary_path[signature] ||= build_index(primary_path)
+	# Returns or builds the index for one complete identity scheme.
+	def index_for(primary_path:, scope_fields:, collections: nil, relationship: nil)
+		signature = [primary_path.nil? ? '__relative_path__' : primary_path, scope_fields.map(&:signature)]
+		@indices_by_identity[signature] ||= build_index(
+			primary_path: primary_path,
+			scope_fields: scope_fields,
+			collections: collections || @collections,
+			relationship: relationship
+		)
 	end
 
-	# Builds the collection and global indices for one scheme.
-	def build_index(primary_path)
-		by_collection = Hash.new { |hash, key| hash[key] = {} }
+	# Builds the collection and global indices for one complete identity scheme.
+	def build_index(primary_path:, scope_fields:, collections:, relationship: nil)
+		by_collection = Hash.new { |hash, key| hash[key] = Hash.new { |nested_hash, nested_key| nested_hash[nested_key] = [] } }
 		by_key = Hash.new { |hash, key| hash[key] = [] }
 
-		@collections.each do |collection|
+		collections.each do |collection|
 			documents_for(collection).each do |document|
 				key = key_for(document, primary_path: primary_path)
-				if by_collection[collection].key?(key)
-					raise ResolutionError, "Primary key `#{key}` is duplicated within collection `#{collection}`."
+				scope = scope_for(document, scope_fields: scope_fields, relationship: relationship)
+				existing_entry = by_collection[collection][key].find { |entry| entry.fetch(:scope) == scope }
+				if existing_entry
+					if scope_fields.empty?
+						raise ResolutionError, "Primary key `#{key}` is duplicated within collection `#{collection}`."
+					end
+
+					raise ResolutionError, "#{relationship_prefix(relationship)}primary key `#{key}` is duplicated within collection `#{collection}` and scope #{scope.inspect} by documents `#{existing_entry.fetch(:document).relative_path}` and `#{document.relative_path}`."
 				end
 
-				by_collection[collection][key] = document
-				by_key[key] << document
+				entry = { document: document, scope: scope }
+				by_collection[collection][key] << entry
+				by_key[key] << entry
 			end
 		end
 
 		{
 			by_collection: by_collection,
-			by_key: by_key,
-			site_wide_unique: by_key.values.all? { |documents| documents.length <= 1 }
+			by_key: by_key
 		}
 	end
 
@@ -123,6 +232,46 @@ class Registry
 		first_hash[second_key]
 	end
 
+	# Raises a field-specific error when key candidates exist but none match the requested complete scope.
+	def raise_scope_mismatch!(candidates:, scope:, scope_fields:, relationship:, referring_document:)
+		candidate = candidates.first
+		field = scope_fields.find do |configured_field|
+			candidate.fetch(:scope).fetch(configured_field.name) != scope.fetch(configured_field.name)
+		end
+		raise ResolutionError, scope_mismatch_message(
+			document: candidate.fetch(:document),
+			field: field,
+			expected_value: scope.fetch(field.name),
+			actual_value: candidate.fetch(:scope).fetch(field.name),
+			relationship: relationship,
+			referring_document: referring_document
+		)
+	end
+
+	# Builds one detailed exact-match failure for a configured scope field.
+	def scope_mismatch_message(document:, field:, expected_value:, actual_value:, relationship:, referring_document:)
+		"#{relationship_prefix(relationship)}target document `#{document.relative_path}` has scope field `#{field.name}` value `#{actual_value.inspect}`, not the required `#{expected_value.inspect}`#{source_suffix(referring_document)}."
+	end
+
+	# Returns true when one literal scope key exists in string or symbol form.
+	def hash_property?(hash, property)
+		hash.key?(property) || hash.key?(property.to_s) || hash.key?(property.to_s.to_sym)
+	end
+
+	# Prefixes an error with its concrete relationship where available.
+	def relationship_prefix(relationship)
+		return '' if relationship.nil? || relationship.to_s.empty?
+
+		"Relationship `#{relationship}`: "
+	end
+
+	# Adds the referring document to lookup diagnostics where available.
+	def source_suffix(document)
+		return '' unless document
+
+		" from document `#{document.relative_path}`"
+	end
+
 	# Implements the README's default relative-path key rule.
 	def default_relative_key(document)
 		document.relative_path.sub(/\A_/, '').sub(/#{Regexp.escape(document.extname)}\z/, '')