fix: improve test coverage and docs for shared-variables guard

- Extend TestRelationsMapperVariablesSharedAcrossConsumers with a values
  row loaded after both consumers, exercising the > 1 guard in
  VariablesValuesForRelation.NewOtherSideRelation
- Replace fragile strings.Count(WarnAndErrorMessages, "variablesFor")
  assertion with AllMessagesTxt check for the exact formatted message
- Fix grammar: "create" → "creates" in linkRelations comment
- Document the > 1 guard mechanism and the remaining edge case where
  values_row is iterated before consumers in docs/relations-validation.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Matovidlo

docs/relations-validation.md

@@ -65,7 +65,13 @@ A values row's `variablesValuesFor` relation is linked by looking up the parent
 
 Calling `GetOneByType(VariablesForRelType)` on Y at this point returns an error ("only one expected, but found 2"). If that error were propagated, it would produce a duplicate "invalid config Y" message alongside the one already generated by Pass 2 validation of Y itself.
 
-To avoid the duplicate, `NewOtherSideRelation` silently returns `(nil, nil, nil)` when `GetOneByType` reports multiple relations — deferring to Pass 2 to emit the canonical warning. The `variablesValuesFor` relation on the values row is left in place; the values row is then transitively excluded from the pull output by the ignore mapper (see below).
+To avoid the duplicate, `NewOtherSideRelation` checks `len(GetByType(VariablesForRelType)) > 1` before calling `GetOneByType`. When multiple relations exist, it returns `(nil, nil, nil)` — deferring to Pass 2 to emit the canonical warning. The `variablesValuesFor` relation on the values row is left in place; the values row is then transitively excluded from the pull output by the ignore mapper (see below).
+
+### Edge case: values row iterated before consumers
+
+If the Loaded() order is `vars_config → values_row → consumer1 → consumer2`, then when `linkRelations(values_row)` runs in Pass 1, Y has zero `variablesFor` entries (consumers have not been processed yet). The `> 1` guard does not fire. `GetOneByType` returns `nil` (no relation found), and `NewOtherSideRelation` returns the "missing relation variablesFor" error — producing an extra warning in the output alongside the "found 2" warning from Pass 2.
+
+This double-warning is a pre-existing edge case. In practice it does not arise because consumer configs always appear in Loaded() before variables values rows (the Storage API returns consumers, and values rows are discovered via the consumer's `variablesValuesFrom` relations). The `> 1` guard eliminates the more common ordering issue; the remaining edge case is benign — both warnings correctly describe the malformed setup.
 
 ## Why the ignore mapper excludes orphaned variables configs
 

internal/pkg/mapper/relations/link.go

@@ -77,7 +77,7 @@ func (m *relationsMapper) AfterRemoteOperation(ctx context.Context, changes *mod
 	return nil
 }
 
-// linkRelations finds the other side of the relation and create a corresponding relation on the other side.
+// linkRelations finds the other side of the relation and creates a corresponding relation on the other side.
 func (m *relationsMapper) linkRelations(object model.ObjectWithRelations, allObjects model.Objects) error {
 	errs := errors.NewMultiError()
 	relations := object.GetRelations()

internal/pkg/mapper/relations/link_test.go

@@ -70,6 +70,9 @@ func TestRelationsMapperLinkRelations(t *testing.T) {
 // TestRelationsMapperVariablesSharedAcrossConsumers verifies that when a variables config
 // is loaded before its consumers in changes.Loaded(), the two-pass approach still produces
 // exactly one warning instead of crashing with "multiple parents defined by relations".
+// It also exercises the > 1 guard in VariablesValuesForRelation.NewOtherSideRelation by
+// including a values row loaded after both consumers so that, during Pass 1, the variables
+// config already holds two variablesFor relations when linkRelations(valuesRow) runs.
 func TestRelationsMapperVariablesSharedAcrossConsumers(t *testing.T) {
 	t.Parallel()
 	state, d := createStateWithMapper(t)
@@ -87,14 +90,19 @@ func TestRelationsMapperVariablesSharedAcrossConsumers(t *testing.T) {
 	}
 	require.NoError(t, state.Set(varsConfig))
 
-	// Consumer 1 — variablesFrom relation pointing to varsKey.
+	// Consumer 1 — variablesFrom and variablesValuesFrom relations pointing to varsKey.
+	// VariablesValuesFromRelation causes linkRelations(consumer1) to add a VariablesValuesFor
+	// relation to the values row, which in turn exercises the > 1 guard when
+	// linkRelations(valuesRow) runs later in Pass 1.
+	valuesRowID := keboola.RowID("val1")
 	consumer1Key := model.ConfigKey{BranchID: branchID, ComponentID: consumerCompID, ID: "consumer1"}
 	consumer1 := &model.ConfigState{
 		ConfigManifest: &model.ConfigManifest{ConfigKey: consumer1Key},
 		Remote: &model.Config{
 			ConfigKey: consumer1Key,
 			Relations: model.Relations{
 				&model.VariablesFromRelation{VariablesID: varsKey.ID},
+				&model.VariablesValuesFromRelation{VariablesValuesID: valuesRowID},
 			},
 		},
 	}
@@ -113,19 +121,31 @@ func TestRelationsMapperVariablesSharedAcrossConsumers(t *testing.T) {
 	}
 	require.NoError(t, state.Set(consumer2))
 
-	// Variables config is first in Loaded() — the ordering that previously caused the crash.
+	// Values row — loaded LAST so that when linkRelations(valuesRow) runs in Pass 1, the
+	// variables config already holds 2 variablesFor relations (added by consumer1 and
+	// consumer2). The > 1 guard in VariablesValuesForRelation.NewOtherSideRelation fires
+	// and returns (nil, nil, nil), preventing a duplicate "invalid config Y" error.
+	valuesRowKey := model.ConfigRowKey{BranchID: branchID, ComponentID: keboola.VariablesComponentID, ConfigID: varsKey.ID, ID: valuesRowID}
+	valuesRow := &model.ConfigRowState{
+		ConfigRowManifest: &model.ConfigRowManifest{ConfigRowKey: valuesRowKey},
+		Remote:            &model.ConfigRow{ConfigRowKey: valuesRowKey},
+	}
+	require.NoError(t, state.Set(valuesRow))
+
+	// Variables config is first in Loaded(), values row is last — both orderings that
+	// previously caused problems are exercised in a single pass.
 	changes := model.NewRemoteChanges()
 	changes.AddLoaded(varsConfig)
 	changes.AddLoaded(consumer1)
 	changes.AddLoaded(consumer2)
+	changes.AddLoaded(valuesRow)
 
 	// Must return nil — the duplicate is a warning, not a fatal error.
 	require.NoError(t, state.Mapper().AfterRemoteOperation(t.Context(), changes))
 
 	// Exactly one warning about the duplicate variablesFor relation.
-	// WarnAndErrorMessages() returns raw JSON; the formatter capitalises sentence starts.
-	msgs := logger.WarnAndErrorMessages()
-	assert.Equal(t, 1, strings.Count(msgs, "variablesFor"))
+	allTxt := logger.AllMessagesTxt()
+	assert.Equal(t, 1, strings.Count(allTxt, `Only one relation "variablesFor" expected, but found 2`))
 	assert.Empty(t, logger.ErrorMessages())
 }