Configuration hardening

internal/pipeline/build.go

@@ -110,6 +110,8 @@ type BuildHAKOptions struct {
 	Progress           ProgressFunc
 	ArchiveNames       []string
 	SourceManifestPath string
+	SkipMusic          bool
+	MusicDatasetIDs    []string
 }
 
 func Build(p *project.Project) (BuildResult, error) {
@@ -195,7 +197,7 @@ func BuildHAKsWithProgress(p *project.Project, progress ProgressFunc) (BuildResu
 }
 
 func BuildHAKsWithOptions(p *project.Project, opts BuildHAKOptions) (BuildResult, error) {
-	return planOrBuildHAKs(p, opts.Progress, true, opts.ArchiveNames, opts.SourceManifestPath)
+	return planOrBuildHAKs(p, opts.Progress, true, opts.ArchiveNames, opts.SourceManifestPath, opts.SkipMusic, opts.MusicDatasetIDs)
 }
 
 func PlanHAKs(p *project.Project) (BuildResult, error) {
@@ -206,15 +208,19 @@ func PlanHAKsWithProgress(p *project.Project, progress ProgressFunc) (BuildResul
 	return planHAKs(p, progress)
 }
 
+func PlanHAKsWithOptions(p *project.Project, opts BuildHAKOptions) (BuildResult, error) {
+	return planOrBuildHAKs(p, opts.Progress, false, opts.ArchiveNames, opts.SourceManifestPath, opts.SkipMusic, opts.MusicDatasetIDs)
+}
+
 func buildHAKs(p *project.Project, progress ProgressFunc) (BuildResult, error) {
-	return planOrBuildHAKs(p, progress, true, nil, "")
+	return planOrBuildHAKs(p, progress, true, nil, "", false, nil)
 }
 
 func planHAKs(p *project.Project, progress ProgressFunc) (BuildResult, error) {
-	return planOrBuildHAKs(p, progress, false, nil, "")
+	return planOrBuildHAKs(p, progress, false, nil, "", false, nil)
 }
 
-func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bool, archiveNames []string, sourceManifestPath string) (result BuildResult, err error) {
+func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bool, archiveNames []string, sourceManifestPath string, skipMusic bool, musicDatasetIDs []string) (result BuildResult, err error) {
 	preserveExistingHAKs := p.EffectiveConfig().Build.KeepExistingHAKs || envBool("SOW_BUILD_HAKS_KEEP_EXISTING")
 
 	progressf(progress, "Validating project...")
@@ -227,9 +233,15 @@ func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bo
 	if err != nil {
 		return BuildResult{}, err
 	}
-	musicAssets, err := prepareMusicAssets(p)
-	if err != nil {
-		return BuildResult{}, err
+	musicAssets := &preparedMusicAssets{SkipSourceRel: map[string]struct{}{}}
+	if !skipMusic {
+		musicAssets, err = prepareMusicAssetsWithOptions(p, musicPrepareOptions{
+			datasetIDs: musicDatasetIDs,
+			write:      writeArchives,
+		})
+		if err != nil {
+			return BuildResult{}, err
+		}
 	}
 	defer func() {
 		if cleanupErr := cleanupPreparedMusicAssets(musicAssets); cleanupErr != nil && err == nil {

internal/pipeline/music.go

@@ -21,16 +21,193 @@ type preparedMusicAssets struct {
 	Summary       CreditsRefreshSummary
 }
 
+type MusicBuildOptions struct {
+	DatasetIDs []string
+	Write      bool
+}
+
+type musicPrepareOptions struct {
+	datasetIDs []string
+	write      bool
+}
+
+type musicSourceGroup struct {
+	DatasetID string
+	Dataset   project.EffectiveMusicDataset
+	SourceDir string
+	OutputDir string
+	Sources   []string
+}
+
+type musicCreditGroup struct {
+	CreditsRoot string
+	SourceDir   string
+	Entries     []music.CreditsEntry
+}
+
+func musicRootPath(p *project.Project, path string) string {
+	if strings.TrimSpace(path) == "" {
+		return p.Root
+	}
+	if filepath.IsAbs(path) {
+		return path
+	}
+	return filepath.Join(p.Root, filepath.FromSlash(path))
+}
+
+func effectiveMusicDatasets(p *project.Project, onlyIDs []string) (map[string]project.EffectiveMusicDataset, error) {
+	effective := p.EffectiveConfig()
+	wanted := map[string]struct{}{}
+	for _, id := range onlyIDs {
+		id = strings.TrimSpace(id)
+		if id != "" {
+			wanted[id] = struct{}{}
+		}
+	}
+	datasets := map[string]project.EffectiveMusicDataset{}
+	for id, dataset := range effective.Music.Datasets {
+		if len(wanted) > 0 {
+			if _, ok := wanted[id]; !ok {
+				continue
+			}
+			delete(wanted, id)
+		}
+		datasets[id] = dataset
+	}
+	if len(wanted) > 0 {
+		unknown := make([]string, 0, len(wanted))
+		for id := range wanted {
+			unknown = append(unknown, id)
+		}
+		sort.Strings(unknown)
+		return nil, fmt.Errorf("unknown music dataset(s): %s", strings.Join(unknown, ", "))
+	}
+	if len(datasets) == 0 && len(wanted) == 0 {
+		for _, rel := range p.Inventory.AssetFiles {
+			ext := strings.ToLower(filepath.Ext(rel))
+			if !music.PathIsUnder("envi/music", rel) {
+				continue
+			}
+			if _, ok := extensionSet(effective.Music.ConvertExtensions)[ext]; ok {
+				datasets["legacy_envi_music"] = project.EffectiveMusicDataset{
+					Source:            "envi/music",
+					Output:            "envi/music",
+					StageRoot:         effective.Music.StageRoot,
+					CreditsRoot:       effective.Music.CreditsRoot,
+					NamingScheme:      effective.Music.NamingScheme,
+					OutputExtension:   effective.Music.OutputExtension,
+					MaxStemLength:     effective.Music.MaxStemLength,
+					PackageMode:       "hak_asset",
+					ConvertExtensions: effective.Music.ConvertExtensions,
+				}
+				break
+			}
+		}
+	}
+	return datasets, nil
+}
+
+func extensionSet(values []string) map[string]struct{} {
+	out := make(map[string]struct{}, len(values))
+	for _, value := range values {
+		value = strings.ToLower(strings.TrimSpace(value))
+		if value != "" {
+			out[value] = struct{}{}
+		}
+	}
+	return out
+}
+
+func datasetForMusicSource(datasets map[string]project.EffectiveMusicDataset, rel, ext string) (string, project.EffectiveMusicDataset, bool) {
+	bestID := ""
+	var best project.EffectiveMusicDataset
+	bestLen := -1
+	for id, dataset := range datasets {
+		if _, ok := extensionSet(dataset.ConvertExtensions)[ext]; !ok {
+			continue
+		}
+		if !music.PathIsUnder(dataset.Source, rel) {
+			continue
+		}
+		if len(dataset.Source) > bestLen {
+			bestID = id
+			best = dataset
+			bestLen = len(dataset.Source)
+		}
+	}
+	return bestID, best, bestID != ""
+}
+
+func plannedMusicAsset(outputRel, sourceRel string) (assetResource, error) {
+	extension := strings.TrimPrefix(strings.ToLower(filepath.Ext(outputRel)), ".")
+	resourceType, ok := erf.HAKResourceTypeForExtension(extension)
+	if !ok {
+		return assetResource{}, fmt.Errorf("unsupported generated music resource extension %q", filepath.Ext(outputRel))
+	}
+	name := strings.ToLower(strings.TrimSuffix(filepath.Base(outputRel), filepath.Ext(outputRel)))
+	return assetResource{
+		Rel: outputRel,
+		Resource: erf.Resource{
+			Name: name,
+			Type: resourceType,
+		},
+		ContentID: "music-plan:" + filepath.ToSlash(sourceRel),
+	}, nil
+}
+
+func BuildMusic(p *project.Project, opts MusicBuildOptions) (BuildResult, error) {
+	prepared, err := prepareMusicAssetsWithOptions(p, musicPrepareOptions{datasetIDs: opts.DatasetIDs, write: opts.Write})
+	if err != nil {
+		return BuildResult{}, err
+	}
+	if err := cleanupPreparedMusicAssets(prepared); err != nil {
+		return BuildResult{}, err
+	}
+	return BuildResult{
+		CreditsArtifactPaths: prepared.Artifacts,
+		CreditsSummary:       prepared.Summary,
+		HAKAssets:            len(prepared.Generated),
+	}, nil
+}
+
 func prepareMusicAssets(p *project.Project) (*preparedMusicAssets, error) {
+	return prepareMusicAssetsWithOptions(p, musicPrepareOptions{write: true})
+}
+
+func prepareMusicAssetsWithOptions(p *project.Project, opts musicPrepareOptions) (*preparedMusicAssets, error) {
 	usedNames := make(map[string]struct{})
-	dirSources := make(map[string][]string)
+	groupsByKey := make(map[string]*musicSourceGroup)
+	datasets, err := effectiveMusicDatasets(p, opts.datasetIDs)
+	if err != nil {
+		return nil, err
+	}
 	for _, rel := range p.Inventory.AssetFiles {
 		rel = filepath.ToSlash(rel)
 		ext := strings.ToLower(filepath.Ext(rel))
 		name := strings.ToLower(strings.TrimSuffix(filepath.Base(rel), filepath.Ext(rel)))
-		if _, convertible := music.ConvertExtensions[ext]; convertible && music.IsMusicAssetPath(rel) {
-			dir := filepath.ToSlash(filepath.Dir(rel))
-			dirSources[dir] = append(dirSources[dir], rel)
+		if datasetID, dataset, ok := datasetForMusicSource(datasets, rel, ext); ok {
+			sourceDir := filepath.ToSlash(filepath.Dir(rel))
+			relDir, err := filepath.Rel(filepath.FromSlash(dataset.Source), filepath.FromSlash(sourceDir))
+			if err != nil {
+				return nil, fmt.Errorf("resolve music source directory %s: %w", sourceDir, err)
+			}
+			relDir = filepath.ToSlash(relDir)
+			outputDir := dataset.Output
+			if relDir != "." && relDir != "" {
+				outputDir = filepath.ToSlash(filepath.Join(outputDir, filepath.FromSlash(relDir)))
+			}
+			key := datasetID + "\x00" + sourceDir
+			group := groupsByKey[key]
+			if group == nil {
+				group = &musicSourceGroup{
+					DatasetID: datasetID,
+					Dataset:   dataset,
+					SourceDir: sourceDir,
+					OutputDir: outputDir,
+				}
+				groupsByKey[key] = group
+			}
+			group.Sources = append(group.Sources, rel)
 			continue
 		}
 		if name != "" {
@@ -41,7 +218,10 @@ func prepareMusicAssets(p *project.Project) (*preparedMusicAssets, error) {
 	result := &preparedMusicAssets{
 		SkipSourceRel: make(map[string]struct{}),
 	}
-	if len(dirSources) == 0 {
+	if len(groupsByKey) == 0 {
+		if !opts.write {
+			return result, nil
+		}
 		writeResult, err := writeCreditsArtifacts(p, nil)
 		if err != nil {
 			return nil, err
@@ -51,57 +231,86 @@ func prepareMusicAssets(p *project.Project) (*preparedMusicAssets, error) {
 		return result, nil
 	}
 
-	dirs := make([]string, 0, len(dirSources))
-	for dir := range dirSources {
-		dirs = append(dirs, dir)
+	groups := make([]*musicSourceGroup, 0, len(groupsByKey))
+	for _, group := range groupsByKey {
+		sort.Strings(group.Sources)
+		groups = append(groups, group)
 	}
-	sort.Strings(dirs)
+	sort.Slice(groups, func(i, j int) bool {
+		if groups[i].SourceDir != groups[j].SourceDir {
+			return groups[i].SourceDir < groups[j].SourceDir
+		}
+		return groups[i].DatasetID < groups[j].DatasetID
+	})
 
-	generatedByDir := make(map[string][]music.CreditsEntry)
-	stageRoot := p.MusicStageDir()
-	result.TempRoots = append(result.TempRoots, stageRoot)
-
-	ffmpegPath, err := music.ResolveFFmpeg()
-	if err != nil {
-		return nil, err
+	creditGroups := make([]musicCreditGroup, 0, len(groups))
+	for _, group := range groups {
+		result.Summary.ScannedDirs = append(result.Summary.ScannedDirs, group.SourceDir)
+		result.Summary.TrackCount += len(group.Sources)
 	}
-	ffprobePath, err := music.ResolveFFprobe()
-	if err != nil {
-		return nil, err
+	ffmpegPath := ""
+	ffprobePath := ""
+	if opts.write {
+		var err error
+		ffmpegPath, err = music.ResolveFFmpegWithConfig(p.MusicFFmpegPath())
+		if err != nil {
+			return nil, err
+		}
+		ffprobePath, err = music.ResolveFFprobeWithConfig(p.MusicFFprobePath())
+		if err != nil {
+			return nil, err
+		}
 	}
 
-	for _, dir := range dirs {
-		sources := append([]string(nil), dirSources[dir]...)
-		sort.Strings(sources)
-		prefix := music.PrefixForDir(p.EffectiveConfig().Music.Prefixes, dir)
-		overlayPath := filepath.Join(p.AssetsDir(), filepath.FromSlash(dir), p.EffectiveConfig().Music.CreditsOverlay)
+	for _, group := range groups {
+		stageRoot := musicRootPath(p, group.Dataset.StageRoot)
+		result.TempRoots = append(result.TempRoots, stageRoot)
+		prefix := music.SanitizePrefix(group.Dataset.Prefix)
+		overlayPath := filepath.Join(p.AssetsDir(), filepath.FromSlash(group.SourceDir), p.EffectiveConfig().Music.CreditsOverlay)
 		overlay, err := music.ParseCreditsOverlay(overlayPath)
 		if err != nil {
 			return nil, fmt.Errorf("parse credits overlay %s: %w", overlayPath, err)
 		}
 
-		entries := make([]music.CreditsEntry, 0, len(sources))
-		for _, rel := range sources {
+		entries := make([]music.CreditsEntry, 0, len(group.Sources))
+		for _, rel := range group.Sources {
 			base := filepath.Base(rel)
 			manual := overlay.Match(base, "")
 			outputFile := ""
 			switch {
 			case manual != nil && strings.TrimSpace(manual.OutputFile) != "":
 				outputFile = strings.ToLower(strings.TrimSpace(manual.OutputFile))
-				if err := music.ValidateManualOutputFile(outputFile); err != nil {
+				if err := music.ValidateManualOutputFileWithRules(outputFile, group.Dataset.OutputExtension, group.Dataset.MaxStemLength); err != nil {
 					return nil, fmt.Errorf("manual credits output for %s: %w", rel, err)
 				}
 				if err := music.ReserveName(strings.TrimSuffix(outputFile, filepath.Ext(outputFile)), usedNames); err != nil {
 					return nil, fmt.Errorf("manual credits output for %s: %w", rel, err)
 				}
 			default:
-				stem, err := music.GenerateStem(base, prefix, usedNames)
+				stem, err := music.GenerateStemWithMax(base, prefix, group.Dataset.MaxStemLength, usedNames)
 				if err != nil {
 					return nil, fmt.Errorf("generate music name for %s: %w", rel, err)
 				}
-				outputFile = stem + ".bmu"
+				outputFile = stem + group.Dataset.OutputExtension
 			}
-			outputRel := filepath.ToSlash(filepath.Join(dir, outputFile))
+			outputRel := filepath.ToSlash(filepath.Join(group.OutputDir, outputFile))
+			result.Summary.Mappings = append(result.Summary.Mappings, MusicFileMapping{
+				Source: rel,
+				Output: outputRel,
+			})
+			result.SkipSourceRel[rel] = struct{}{}
+
+			if !opts.write {
+				if group.Dataset.PackageMode == "hak_asset" {
+					asset, err := plannedMusicAsset(outputRel, rel)
+					if err != nil {
+						return nil, err
+					}
+					result.Generated = append(result.Generated, asset)
+				}
+				continue
+			}
+
 			metadata, err := music.ProbeMetadata(ffprobePath, filepath.Join(p.AssetsDir(), filepath.FromSlash(rel)))
 			if err != nil {
 				return nil, fmt.Errorf("probe music metadata for %s: %w", rel, err)
@@ -125,36 +334,50 @@ func prepareMusicAssets(p *project.Project) (*preparedMusicAssets, error) {
 			if err := music.ConvertSource(ffmpegPath, filepath.Join(p.AssetsDir(), filepath.FromSlash(rel)), stagePath); err != nil {
 				return nil, fmt.Errorf("convert music %s: %w", rel, err)
 			}
-			resourceInfo, err := assetResourceFromPath(stagePath, outputRel, lfsAssetInfo{}, false)
-			if err != nil {
-				return nil, fmt.Errorf("load converted music %s: %w", outputRel, err)
+			if group.Dataset.PackageMode == "hak_asset" {
+				resourceInfo, err := assetResourceFromPath(stagePath, outputRel, lfsAssetInfo{}, false)
+				if err != nil {
+					return nil, fmt.Errorf("load converted music %s: %w", outputRel, err)
+				}
+				info, err := os.Stat(stagePath)
+				if err != nil {
+					return nil, fmt.Errorf("stat converted music %s: %w", stagePath, err)
+				}
+				result.Generated = append(result.Generated, assetResource{
+					Rel:       outputRel,
+					Resource:  resourceInfo.Resource,
+					Size:      erf.ArchiveSize([]erf.Resource{resourceInfo.Resource}),
+					CreatedAt: info.ModTime(),
+					ContentID: resourceInfo.ContentID,
+				})
 			}
-			info, err := os.Stat(stagePath)
-			if err != nil {
-				return nil, fmt.Errorf("stat converted music %s: %w", stagePath, err)
-			}
-			result.Generated = append(result.Generated, assetResource{
-				Rel:       outputRel,
-				Resource:  resourceInfo.Resource,
-				Size:      erf.ArchiveSize([]erf.Resource{resourceInfo.Resource}),
-				CreatedAt: info.ModTime(),
-				ContentID: resourceInfo.ContentID,
-			})
-			result.SkipSourceRel[rel] = struct{}{}
 			entries = append(entries, entry)
 		}
-		if err := music.ValidateOverlayEntries(dir, overlay, entries); err != nil {
-			return nil, err
+		if opts.write {
+			if err := music.ValidateOverlayEntries(group.SourceDir, overlay, entries); err != nil {
+				return nil, err
+			}
+			creditGroups = append(creditGroups, musicCreditGroup{
+				CreditsRoot: group.Dataset.CreditsRoot,
+				SourceDir:   group.SourceDir,
+				Entries:     entries,
+			})
 		}
-		generatedByDir[dir] = entries
 	}
 
-	writeResult, err := writeCreditsArtifacts(p, generatedByDir)
+	if !opts.write {
+		sort.Slice(result.Generated, func(i, j int) bool {
+			return compareResourceKeys(result.Generated[i].Resource, result.Generated[j].Resource) < 0
+		})
+		return result, nil
+	}
+
+	writeResult, err := writeCreditsArtifacts(p, creditGroups)
 	if err != nil {
 		return nil, err
 	}
-	writeResult.Summary.ScannedDirs = append(writeResult.Summary.ScannedDirs, dirs...)
-	writeResult.Summary.TrackCount = len(result.Generated)
+	writeResult.Summary.ScannedDirs = append(writeResult.Summary.ScannedDirs, result.Summary.ScannedDirs...)
+	writeResult.Summary.TrackCount = result.Summary.TrackCount
 	result.Artifacts = writeResult.Artifacts
 	result.Summary = writeResult.Summary
 	sort.Slice(result.Generated, func(i, j int) bool {
@@ -168,19 +391,24 @@ type creditsArtifactWriteResult struct {
 	Summary   CreditsRefreshSummary
 }
 
-func writeCreditsArtifacts(p *project.Project, generatedByDir map[string][]music.CreditsEntry) (creditsArtifactWriteResult, error) {
-	creditsRoot := p.CreditsDir()
+func writeCreditsArtifacts(p *project.Project, generated []musicCreditGroup) (creditsArtifactWriteResult, error) {
+	defaultCreditsRoot := p.CreditsDir()
 	sources := make([]music.CreditsSource, 0)
-	desiredFiles := make(map[string][]byte)
+	desiredByRoot := map[string]map[string][]byte{}
 	summary := CreditsRefreshSummary{}
-	if generatedByDir != nil {
-		dirs := make([]string, 0, len(generatedByDir))
-		for dir := range generatedByDir {
-			dirs = append(dirs, dir)
-		}
-		sort.Strings(dirs)
-		for _, dir := range dirs {
-			entries := append([]music.CreditsEntry(nil), generatedByDir[dir]...)
+	if generated != nil {
+		sort.Slice(generated, func(i, j int) bool {
+			if generated[i].SourceDir != generated[j].SourceDir {
+				return generated[i].SourceDir < generated[j].SourceDir
+			}
+			return generated[i].CreditsRoot < generated[j].CreditsRoot
+		})
+		for _, group := range generated {
+			creditsRoot := musicRootPath(p, group.CreditsRoot)
+			if desiredByRoot[creditsRoot] == nil {
+				desiredByRoot[creditsRoot] = map[string][]byte{}
+			}
+			entries := append([]music.CreditsEntry(nil), group.Entries...)
 			sort.Slice(entries, func(i, j int) bool {
 				if strings.ToLower(entries[i].Artist) != strings.ToLower(entries[j].Artist) {
 					return strings.ToLower(entries[i].Artist) < strings.ToLower(entries[j].Artist)
@@ -190,8 +418,8 @@ func writeCreditsArtifacts(p *project.Project, generatedByDir map[string][]music
 				}
 				return strings.ToLower(entries[i].OutputFile) < strings.ToLower(entries[j].OutputFile)
 			})
-			outputPath := filepath.Join(creditsRoot, filepath.FromSlash(dir), p.EffectiveConfig().Music.CreditsOverlay)
-			desiredFiles[outputPath] = []byte(music.RenderCreditsMarkdown(entries))
+			outputPath := filepath.Join(creditsRoot, filepath.FromSlash(group.SourceDir), p.EffectiveConfig().Music.CreditsOverlay)
+			desiredByRoot[creditsRoot][outputPath] = []byte(music.RenderCreditsMarkdown(entries))
 			summary.GeneratedPaths = append(summary.GeneratedPaths, outputPath)
 			for _, entry := range entries {
 				summary.Mappings = append(summary.Mappings, MusicFileMapping{
@@ -237,27 +465,42 @@ func writeCreditsArtifacts(p *project.Project, generatedByDir map[string][]music
 	}
 
 	sort.Slice(sources, func(i, j int) bool { return sources[i].Path < sources[j].Path })
-	inventoryPath := filepath.Join(creditsRoot, "credits.json")
 	payload, err := json.MarshalIndent(music.CreditsInventory{Sources: sources}, "", "  ")
 	if err != nil {
 		return creditsArtifactWriteResult{}, fmt.Errorf("marshal credits inventory: %w", err)
 	}
 	payload = append(payload, '\n')
-	desiredFiles[inventoryPath] = payload
-	if err := os.MkdirAll(creditsRoot, 0o755); err != nil {
-		return creditsArtifactWriteResult{}, fmt.Errorf("create credits dir: %w", err)
+	if len(desiredByRoot) == 0 {
+		desiredByRoot[defaultCreditsRoot] = map[string][]byte{}
 	}
-	changedFiles, err := music.SyncGeneratedCreditsArtifacts(creditsRoot, desiredFiles)
-	if err != nil {
-		return creditsArtifactWriteResult{}, err
+	artifacts := make([]string, 0)
+	changedFiles := 0
+	roots := make([]string, 0, len(desiredByRoot))
+	for root := range desiredByRoot {
+		roots = append(roots, root)
 	}
-	artifacts := make([]string, 0, len(desiredFiles))
-	for path := range desiredFiles {
-		artifacts = append(artifacts, path)
+	sort.Strings(roots)
+	for _, creditsRoot := range roots {
+		desiredFiles := desiredByRoot[creditsRoot]
+		inventoryPath := filepath.Join(creditsRoot, "credits.json")
+		desiredFiles[inventoryPath] = payload
+		if err := os.MkdirAll(creditsRoot, 0o755); err != nil {
+			return creditsArtifactWriteResult{}, fmt.Errorf("create credits dir: %w", err)
+		}
+		changed, err := music.SyncGeneratedCreditsArtifacts(creditsRoot, desiredFiles)
+		if err != nil {
+			return creditsArtifactWriteResult{}, err
+		}
+		changedFiles += changed
+		for path := range desiredFiles {
+			artifacts = append(artifacts, path)
+		}
+		if summary.InventoryPath == "" {
+			summary.InventoryPath = inventoryPath
+		}
 	}
 	sort.Strings(artifacts)
 	summary.ArtifactPaths = append(summary.ArtifactPaths, artifacts...)
-	summary.InventoryPath = inventoryPath
 	summary.ChangedFiles = changedFiles
 	return creditsArtifactWriteResult{
 		Artifacts: artifacts,

internal/pipeline/pipeline_test.go

@@ -2769,4 +2769,153 @@ func TestBuildHAKsConvertsMusicSourcesAndWritesCreditsArtifacts(t *testing.T) {
 	}
 }
 
+func TestBuildHAKsUsesExplicitMusicDatasetOutsideLegacyRoot(t *testing.T) {
+	root := t.TempDir()
+	mustMkdir(t, filepath.Join(root, "assets", "audio", "westgate"))
+	mustMkdir(t, filepath.Join(root, "build"))
 
+	ffprobePath := filepath.Join(root, "tools", "ffprobe")
+	ffmpegPath := filepath.Join(root, "tools", "ffmpeg")
+	mustMkdir(t, filepath.Dir(ffprobePath))
+	mustWriteFile(t, ffprobePath, "#!/bin/sh\nprintf '%s\\n' '{\"format\":{\"tags\":{\"artist\":\"Dataset Artist\",\"title\":\"Dataset Title\"}}}'\n")
+	mustWriteFile(t, ffmpegPath, "#!/bin/sh\nfor last; do :; done\nprintf 'dataset-bmu' > \"$last\"\n")
+	if err := os.Chmod(ffprobePath, 0o755); err != nil {
+		t.Fatalf("chmod ffprobe: %v", err)
+	}
+	if err := os.Chmod(ffmpegPath, 0o755); err != nil {
+		t.Fatalf("chmod ffmpeg: %v", err)
+	}
+
+	mustWriteFile(t, filepath.Join(root, "nwn-tool.yaml"), `
+module:
+  name: Test Assets
+  resref: testassets
+paths:
+  assets: assets
+  build: build
+music:
+  tools:
+    ffmpeg: tools/ffmpeg
+    ffprobe: tools/ffprobe
+  defaults:
+    credits_root: custom-credits
+  datasets:
+    westgate_audio:
+      source: audio/westgate
+      output: generated/music
+      prefix: wg_
+haks:
+  - name: music
+    priority: 1
+    max_bytes: 1048576
+    split: false
+    include:
+      - generated/music/**
+`)
+	mustWriteFile(t, filepath.Join(root, "assets", "audio", "westgate", "Theme Song.mp3"), "source-mp3")
+
+	p, err := project.Load(root)
+	if err != nil {
+		t.Fatalf("load project: %v", err)
+	}
+	if err := p.ValidateLayout(); err != nil {
+		t.Fatalf("validate layout: %v", err)
+	}
+	if err := p.Scan(); err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+
+	result, err := BuildHAKs(p)
+	if err != nil {
+		t.Fatalf("build haks: %v", err)
+	}
+	if result.CreditsSummary.TrackCount != 1 {
+		t.Fatalf("expected one music track, got %#v", result.CreditsSummary)
+	}
+	manifestRaw, err := os.ReadFile(filepath.Join(root, "build", "haks.json"))
+	if err != nil {
+		t.Fatalf("read manifest: %v", err)
+	}
+	manifestText := string(manifestRaw)
+	if !strings.Contains(manifestText, "generated/music/wg_theme.bmu") {
+		t.Fatalf("expected dataset output resource in manifest, got:\n%s", manifestText)
+	}
+	if strings.Contains(manifestText, "audio/westgate/Theme Song.mp3") {
+		t.Fatalf("did not expect source mp3 in manifest, got:\n%s", manifestText)
+	}
+	creditsRaw, err := os.ReadFile(filepath.Join(root, "custom-credits", "audio", "westgate", "CREDITS.md"))
+	if err != nil {
+		t.Fatalf("read generated dataset credits: %v", err)
+	}
+	if !strings.Contains(string(creditsRaw), "Dataset Artist") || !strings.Contains(string(creditsRaw), "wg_theme.bmu") {
+		t.Fatalf("unexpected generated credits:\n%s", string(creditsRaw))
+	}
+}
+
+func TestPlanHAKsDoesNotTranscodeMusicSources(t *testing.T) {
+	root := t.TempDir()
+	mustMkdir(t, filepath.Join(root, "assets", "audio", "westgate"))
+	mustMkdir(t, filepath.Join(root, "build"))
+
+	ffmpegPath := filepath.Join(root, "tools", "ffmpeg")
+	mustMkdir(t, filepath.Dir(ffmpegPath))
+	mustWriteFile(t, ffmpegPath, "#!/bin/sh\necho should-not-run >&2\nexit 42\n")
+	if err := os.Chmod(ffmpegPath, 0o755); err != nil {
+		t.Fatalf("chmod ffmpeg: %v", err)
+	}
+
+	mustWriteFile(t, filepath.Join(root, "nwn-tool.yaml"), `
+module:
+  name: Test Assets
+  resref: testassets
+paths:
+  assets: assets
+  build: build
+music:
+  tools:
+    ffmpeg: tools/ffmpeg
+    ffprobe: tools/ffprobe
+  datasets:
+    westgate_audio:
+      source: audio/westgate
+      output: generated/music
+      prefix: wg_
+haks:
+  - name: music
+    priority: 1
+    max_bytes: 1048576
+    split: false
+    include:
+      - generated/music/**
+`)
+	mustWriteFile(t, filepath.Join(root, "assets", "audio", "westgate", "Theme Song.mp3"), "source-mp3")
+
+	p, err := project.Load(root)
+	if err != nil {
+		t.Fatalf("load project: %v", err)
+	}
+	if err := p.ValidateLayout(); err != nil {
+		t.Fatalf("validate layout: %v", err)
+	}
+	if err := p.Scan(); err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+
+	result, err := PlanHAKs(p)
+	if err != nil {
+		t.Fatalf("plan haks: %v", err)
+	}
+	if result.CreditsSummary.TrackCount != 1 {
+		t.Fatalf("expected one planned music track, got %#v", result.CreditsSummary)
+	}
+	manifestRaw, err := os.ReadFile(filepath.Join(root, "build", "haks.json"))
+	if err != nil {
+		t.Fatalf("read manifest: %v", err)
+	}
+	if !strings.Contains(string(manifestRaw), "generated/music/wg_theme.bmu") {
+		t.Fatalf("expected planned generated music in manifest, got:\n%s", string(manifestRaw))
+	}
+	if _, err := os.Stat(filepath.Join(root, ".cache", "music")); !os.IsNotExist(err) {
+		t.Fatalf("plan-only should not stage music, stat err=%v", err)
+	}
+}