Add family artifact selection and provenance

internal/artifacts/effective_set.go

@@ -13,9 +13,17 @@ import (
 // analyze invocation will execute.
 type EffectiveArtifactSet struct {
 	keys     []string
+	origins  map[string]EffectiveArtifactOrigin
 	resolved bool
 }
 
+// EffectiveArtifactOrigin identifies a concrete artifact produced by a
+// resolved family declaration.
+type EffectiveArtifactOrigin struct {
+	Family      string
+	CharacterID string
+}
+
 // ResolveEffectiveArtifactSet applies an explicit artifact selection when one
 // is supplied; otherwise it selects the configured enabled artifacts.
 func ResolveEffectiveArtifactSet(
@@ -88,6 +96,27 @@ func (s EffectiveArtifactSet) Resolved() bool {
 	return s.resolved
 }
 
+// WithOrigins attaches optional resolution provenance without changing the
+// selected concrete keys or lookup semantics.
+func (s EffectiveArtifactSet) WithOrigins(origins map[string]EffectiveArtifactOrigin) EffectiveArtifactSet {
+	if len(origins) == 0 {
+		return s
+	}
+	s.origins = make(map[string]EffectiveArtifactOrigin, len(origins))
+	for key, origin := range origins {
+		if s.Includes(key) {
+			s.origins[key] = origin
+		}
+	}
+	return s
+}
+
+// Origin reports optional family provenance for a concrete artifact key.
+func (s EffectiveArtifactSet) Origin(key string) (EffectiveArtifactOrigin, bool) {
+	origin, ok := s.origins[strings.TrimSpace(key)]
+	return origin, ok
+}
+
 func newEffectiveArtifactSet(set map[string]struct{}) EffectiveArtifactSet {
 	keys := make([]string, 0, len(set))
 	for key := range set {