add content-addressed hak source mode (#7)

Reviewed-on: #7
Co-authored-by: vickydotbat <vickydotbat@tutamail.com>
Co-committed-by: vickydotbat <vickydotbat@tutamail.com>

.gitea/workflows/sync-wrappers.yml

@@ -0,0 +1,50 @@
+# Auto-PR canonical wrapper updates to consumer repos when wrappers/ changes on
+# main. Maintenance automation (not artifact publishing), so it is allowed on a
+# main push under the D7 trigger standard. Requires WRAPPER_SYNC_TOKEN: a bot
+# user's token with content+PR write to the consumer repos (never committed).
+name: sync-wrappers
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'wrappers/crucible.sh'
+      - 'wrappers/crucible.ps1'
+
+jobs:
+  sync:
+    runs-on: nix-docker
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Open sync PRs to consumers
+        env:
+          TOKEN: ${{ secrets.WRAPPER_SYNC_TOKEN }}
+          SERVER: ${{ github.server_url }}
+          SRC_SHA: ${{ github.sha }}
+        run: |
+          nix develop --command bash -c '
+            set -euo pipefail
+            host="$(echo "$SERVER" | sed -E "s#https?://##")"
+            branch="chore/sync-wrappers-$(echo "$SRC_SHA" | cut -c1-12)"
+            grep -vE "^\s*#|^\s*$" wrappers/consumers.txt | while read -r target; do
+              echo "== syncing $target =="
+              work="$(mktemp -d)"
+              git clone "https://oauth2:${TOKEN}@${host}/${target}.git" "$work"
+              cp wrappers/crucible.sh wrappers/crucible.ps1 "$work"/
+              ( cd "$work"
+                git config user.name  "crucible-sync-bot"
+                git config user.email "bot@westgate.pw"
+                if git diff --quiet; then echo "no changes for $target"; exit 0; fi
+                git checkout -b "$branch"
+                git add crucible.sh crucible.ps1
+                git commit -m "chore: sync crucible wrappers from sow-tools@${SRC_SHA}"
+                git push -f origin "$branch"
+                curl -fsS -X POST \
+                  -H "Authorization: token ${TOKEN}" -H "Content-Type: application/json" \
+                  "${SERVER}/api/v1/repos/${target}/pulls" \
+                  -d "{\"head\":\"${branch}\",\"base\":\"main\",\"title\":\"chore: sync crucible wrappers from sow-tools\"}" || true
+              )
+              rm -rf "$work"
+            done
+          '

.gitignore

@@ -6,8 +6,8 @@ nwn-tool
 sow-toolkit
 
 # Go / build cache
-.cache/
+.cache/*
-.cache/**
+!.cache/.gitkeep
 
 # nix build symlink
 result

AGENTS.md

@@ -5,10 +5,9 @@ alwaysApply: true
 
 # sow-tools / Crucible Agent Guide
 
-This repo owns the **builder logic** for the migration: one Go module
+This repo owns the **builder logic:** one Go module
 (`git.westgate.pw/ShadowsOverWestgate/sow-tools`) producing the `crucible`
-dispatcher and the `crucible-<name>` binaries (D11). Read
+dispatcher and the `crucible-<name>` binaries.
-`../AGENTS.md` (migration hub) and `../../KICKOFF_PROMPT.md` first.
 
 ## What this repo owns / does not own
 
@@ -20,19 +19,11 @@ is `sow-platform`).
 
 ## Rules
 
-1. **Migrated logic, not a fresh rewrite.** The `internal/` packages (`app`,
+1. **Fail closed, never fake.** A builder with no migrated logic yet (`depot`)
-   `pipeline`, `project`, `erf`, `gff`, `topdata`, `music`, `changelog`,
-   `validator`) were folded in from `gitea/sow-tools` at cutover; wired builders
-   delegate to `internal/app`'s command surface. Keep them in step with upstream
-   fixes rather than diverging silently.
-2. **Fail closed, never fake.** A builder with no migrated logic yet (`depot`)
    exits `70`. Do not stub a builder to emit a placeholder artifact.
-3. **Binaries are not committed.** They are CI artifacts / image layers (D19).
+2. **Binaries are not committed.** They are CI artifacts / image layers.
    `/bin/`, `*.exe`, `nwn-tool`, `sow-toolkit` are gitignored.
-4. **No home-dir / `NWN_ROOT` guessing.** Builders take roots explicitly via
+3. **The registry is the command surface.** `internal/dispatch.Registry` is the
-   flag or env (project resolution is CWD-based, never `$HOME`). See
-   [`docs/consumer-contract.md`](docs/consumer-contract.md).
-5. **The registry is the command surface.** `internal/dispatch.Registry` is the
    single source of truth; keep it in sync with `cmd/` and
    [`docs/command-surface.md`](docs/command-surface.md). Adding a builder = a
    `cmd/crucible-<name>/main.go` shim + a `Registry` entry + a doc row.
@@ -40,11 +31,8 @@ is `sow-platform`).
 ## Wiring a builder
 
 1. Ensure the relevant `internal/` package(s) cover the work.
-2. Add the legacy command(s) to the builder's `Legacy`/`Extra` set and set
+2. Add tests; keep outputs deterministic (same input → same bytes).
-   `Wired: true` in `internal/dispatch`; the dispatcher delegates to
+3. `make check` must stay green; update `make smoke` to expect the wired exit.
-   `app.Run`. `depot` is the remaining unwired builder.
-3. Add tests; keep outputs deterministic (same input → same bytes).
-4. `make check` must stay green; update `make smoke` to expect the wired exit.
 
 ## Commands
 
@@ -54,7 +42,3 @@ make build                  # cmd/* -> ./bin
 make smoke                  # assert fail-closed contract
 make image                  # crucible:<sha>
 ```
-
-## Git
-
-Never commit, branch, or push. Suggest a commit message; let the operator do it.

README.md

@@ -41,6 +41,30 @@ See [`docs/migration-from-nwn-tool.md`](docs/migration-from-nwn-tool.md) for wha
 was done and what remains (the consumer `--manifest/--source/--out` flag contract
 is the open Phase-6 item).
 
+## Quick start (no Nix)
+
+Teammates without Nix don't build anything — they run the bootstrap wrapper,
+which downloads the latest released `crucible` for your OS and runs it:
+
+```bash
+./crucible            # interactive menu (pick a command)
+./crucible module build
+./crucible topdata validate-topdata
+```
+
+Windows (PowerShell):
+
+```powershell
+.\crucible.ps1 module build
+```
+
+The binary is cached under `~/.cache/crucible/<version>/` (`%LOCALAPPDATA%\crucible`
+on Windows); `--repo-local` caches inside the repo instead. Private releases:
+set `CRUCIBLE_TOKEN` or write the token to `~/.config/crucible/token`.
+
+Only the **music** builder needs `ffmpeg`; everything else has zero dependencies.
+If you run a music command without it, Crucible prints a per-OS install hint.
+
 ## Develop
 
 Self-contained (D8) — a host with only Nix can run everything:
@@ -58,12 +82,18 @@ This retires the old habit of checking in `nwn-tool` / `sow-toolkit`.
 
 ## CI
 
-PR-first (D7): every check runs on pull requests and on push to `main`.
+PR-first (D7): checks run on pull requests and on push to `main`; the only
+publish event is a `v*` tag (see `sow-docs/runbooks/ci-trigger-standard.md`).
 
-- `test.yml` — vet, test, shellcheck, yamllint, binary smoke.
+- `test.yml` — vet, test, shellcheck, yamllint, binary smoke (PR + main).
-- `build-image.yml` — build `registry.westgate.pw/deployment/crucible:<sha>`; publish
+- `test-image.yml` — build the OCI image to prove it compiles (PR + main, no push).
-  only on `main`. PRs build but never push. No mutable tags.
+- `build-binaries.yml` — cross-build all targets (PR + main); on a `v*` tag, upload
-- `release.yml` — tag-gated binary bundles; image re-tag is wired in Phase 6.
+  the binaries, `SHA256SUMS`, and the wrappers to the Gitea release.
+- `build-image.yml` — on a `v*` tag, build and publish
+  `registry.westgate.pw/deployment/crucible:<sha>`.
+- `publish-image.yml` — manual `workflow_dispatch` break-glass republish.
+- `sync-wrappers.yml` — on a `main` push that touches `wrappers/`, auto-PR the
+  canonical wrappers to the consumer repos in `wrappers/consumers.txt`.
 
 ## Consumers
 

docs/command-surface.md

@@ -45,6 +45,22 @@ crucible changelog [args]   -> legacy `build-changelog`
 `crucible list` is machine-readable so CI can enumerate builders without parsing
 help text.
 
+## HAK builder source modes
+
+```text
+build-haks [--hak <hak-name> ...] [--archive <archive-name> ...]
+  [--source-manifest <path>] [--content-addressed-root <path>]
+  [--plan-only] [--skip-music] [--music-dataset <id> ...]
+  [--quiet|--verbose|--debug]
+```
+
+When a source manifest contains `asset_sources`, pass
+`--content-addressed-root <directory>` (or
+`--content-addressed-root=<directory>`). Crucible resolves each declared SHA-256
+under `sha256/<first-two>/<next-two>/<full-sha256>` and verifies streamed bytes
+while writing the selected HAK archives. Source manifests without
+`asset_sources` continue to use the configured assets tree.
+
 ## Global flags (planned, at wiring time)
 
 `--quiet`, `--verbose`, `--debug` (the legacy verbosity model), passed after the

docs/consumer-contract.md

@@ -24,14 +24,17 @@ quoting stays correct.
 
 ## In CI (preferred)
 
-Run the consumer job inside the pinned image and the binaries are on `PATH`:
+**OPERATOR NOTE: Stop. Do not do it this way.**
+**Use the pinned `prod.yml` version. That's what it's there for.**
+
+~~Run the consumer job inside the pinned image and the binaries are on `PATH`:~~
 
 ```yaml
 container:
-  image: registry.westgate.pw/deployment/crucible:<sha>   # pinned, immutable
+  image: registry.westgate.pw/deployment/crucible:<sha> # pinned, immutable
 ```
 
-No host install, no `$HOME` layout, no developer machine assumptions.
+~~No host install, no `$HOME` layout, no developer machine assumptions.~~
 
 ## `NWN_ROOT` rule
 

internal/app/app.go

@@ -466,13 +466,14 @@ func relPathFromRoot(root, path string) string {
 }
 
 type buildHAKOptions struct {
-	filteredHAKs     []string
+	filteredHAKs         []string
-	filteredArchives []string
+	filteredArchives     []string
-	sourceManifest   string
+	sourceManifest       string
-	musicDatasets    []string
+	contentAddressedRoot string
-	skipMusic        bool
+	musicDatasets        []string
-	planOnly         bool
+	skipMusic            bool
-	logLevel         logLevel
+	planOnly             bool
+	logLevel             logLevel
 }
 
 type logLevel int
@@ -1045,11 +1046,12 @@ func runBuildHAKs(ctx context) error {
 	defer spin.stop()
 	var result pipeline.BuildResult
 	pipelineOpts := pipeline.BuildHAKOptions{
-		Progress:           console.progress,
+		Progress:             console.progress,
-		ArchiveNames:       opts.filteredArchives,
+		ArchiveNames:         opts.filteredArchives,
-		SourceManifestPath: opts.sourceManifest,
+		SourceManifestPath:   opts.sourceManifest,
-		SkipMusic:          opts.skipMusic,
+		ContentAddressedRoot: opts.contentAddressedRoot,
-		MusicDatasetIDs:    opts.musicDatasets,
+		SkipMusic:            opts.skipMusic,
+		MusicDatasetIDs:      opts.musicDatasets,
 	}
 	if opts.planOnly {
 		result, err = pipeline.PlanHAKsWithOptions(p, pipelineOpts)
@@ -1074,7 +1076,7 @@ func parseBuildHAKArgs(args []string) (buildHAKOptions, error) {
 		arg := args[index]
 		switch arg {
 		case "-h", "--help":
-			return opts, errors.New("usage: build-haks [--hak <hak-name> ...] [--archive <archive-name> ...] [--source-manifest <path>] [--plan-only] [--skip-music] [--music-dataset <id> ...] [--quiet|--verbose|--debug]")
+			return opts, errors.New("usage: build-haks [--hak <hak-name> ...] [--archive <archive-name> ...] [--source-manifest <path>] [--content-addressed-root <path>] [--plan-only] [--skip-music] [--music-dataset <id> ...] [--quiet|--verbose|--debug]")
 		case "--hak":
 			index++
 			if index >= len(args) {
@@ -1109,6 +1111,12 @@ func parseBuildHAKArgs(args []string) (buildHAKOptions, error) {
 				return opts, errors.New("--source-manifest requires a value")
 			}
 			opts.sourceManifest = args[index]
+		case "--content-addressed-root":
+			index++
+			if index >= len(args) {
+				return opts, errors.New("--content-addressed-root requires a value")
+			}
+			opts.contentAddressedRoot = args[index]
 		default:
 			if value, ok, err := requireInlineFlagValue(arg, "--hak"); ok || err != nil {
 				if err != nil {
@@ -1131,6 +1139,13 @@ func parseBuildHAKArgs(args []string) (buildHAKOptions, error) {
 				opts.sourceManifest = value
 				continue
 			}
+			if value, ok, err := requireInlineFlagValue(arg, "--content-addressed-root"); ok || err != nil {
+				if err != nil {
+					return opts, err
+				}
+				opts.contentAddressedRoot = value
+				continue
+			}
 			if value, ok, err := requireInlineFlagValue(arg, "--music-dataset"); ok || err != nil {
 				if err != nil {
 					return opts, err

internal/app/app_test.go

@@ -11,6 +11,48 @@ import (
 	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/pipeline"
 )
 
+func TestParseBuildHAKArgsContentAddressedRoot(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{
+			name: "separated",
+			args: []string{"--content-addressed-root", "/var/cache/blobs"},
+			want: "/var/cache/blobs",
+		},
+		{
+			name: "inline",
+			args: []string{"--content-addressed-root=/var/cache/blobs"},
+			want: "/var/cache/blobs",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			opts, err := parseBuildHAKArgs(tt.args)
+			if err != nil {
+				t.Fatalf("parse build-haks args: %v", err)
+			}
+			if opts.contentAddressedRoot != tt.want {
+				t.Fatalf("content-addressed root = %q, want %q", opts.contentAddressedRoot, tt.want)
+			}
+		})
+	}
+}
+
+func TestParseBuildHAKArgsHelpListsContentAddressedRoot(t *testing.T) {
+	_, err := parseBuildHAKArgs([]string{"--help"})
+	if err == nil {
+		t.Fatal("expected help usage error")
+	}
+	const want = "usage: build-haks [--hak <hak-name> ...] [--archive <archive-name> ...] [--source-manifest <path>] [--content-addressed-root <path>] [--plan-only] [--skip-music] [--music-dataset <id> ...] [--quiet|--verbose|--debug]"
+	if err.Error() != want {
+		t.Fatalf("help usage = %q, want %q", err.Error(), want)
+	}
+}
+
 func TestRunBuildTopPackageUsesCachedCompiledOutputs(t *testing.T) {
 	root := t.TempDir()
 	mkdirAll(t, filepath.Join(root, "build"))

internal/dispatch/dispatch.go

@@ -249,8 +249,10 @@ func usage(w io.Writer) {
 	fmt.Fprintf(w, "  list              list builders (one per line: name<TAB>bin<TAB>summary)\n")
 	fmt.Fprintf(w, "  config [args]     inspect/validate effective configuration\n")
 	fmt.Fprintf(w, "  changelog [args]  generate the release changelog\n")
-	fmt.Fprintf(w, "\nNWN_ROOT must be passed explicitly (env or flag); crucible never guesses\n")
+	fmt.Fprintf(w, "\nBuilders read all inputs from the project tree (nwn-tool.yaml + data/); no\n")
-	fmt.Fprintf(w, "from $HOME. See docs/consumer-contract.md.\n")
+	fmt.Fprintf(w, "NWN install is required. If a builder ever needs an NWN root, it must be\n")
+	fmt.Fprintf(w, "passed explicitly via NWN_ROOT; crucible never guesses from $HOME. See\n")
+	fmt.Fprintf(w, "docs/consumer-contract.md.\n")
 }
 
 func list(w io.Writer) {

internal/erf/erf.go

@@ -2,14 +2,19 @@ package erf
 
 import (
 	"bytes"
+	"crypto/sha256"
 	"encoding/binary"
+	"encoding/hex"
 	"fmt"
 	"io"
 	"os"
+	"regexp"
 	"sort"
 	"strings"
 )
 
+var expectedSHA256Pattern = regexp.MustCompile(`^[0-9a-f]{64}$`)
+
 const (
 	headerSize = 160
 	versionV10 = "V1.0"
@@ -30,6 +35,9 @@ type Resource struct {
 	Data       []byte
 	SourcePath string
 	Size       int64
+	// ExpectedSHA256, when set, is the lowercase hex SHA-256 the streamed
+	// SourcePath payload must hash to. A mismatch fails the write.
+	ExpectedSHA256 string
 }
 
 type header struct {
@@ -407,18 +415,29 @@ func writeResourceData(w io.Writer, resource Resource) error {
 		return err
 	}
 
+	if resource.ExpectedSHA256 != "" && !expectedSHA256Pattern.MatchString(resource.ExpectedSHA256) {
+		return fmt.Errorf("resource %q has invalid expected sha256", resource.SourcePath)
+	}
+
 	file, err := os.Open(resource.SourcePath)
 	if err != nil {
 		return fmt.Errorf("open resource %q: %w", resource.SourcePath, err)
 	}
 	defer file.Close()
 
-	written, err := io.Copy(w, file)
+	hash := sha256.New()
+	written, err := io.Copy(io.MultiWriter(w, hash), file)
 	if err != nil {
 		return fmt.Errorf("copy resource %q: %w", resource.SourcePath, err)
 	}
 	if resource.Size > 0 && written != resource.Size {
 		return fmt.Errorf("copy resource %q: expected %d bytes, wrote %d", resource.SourcePath, resource.Size, written)
 	}
+	if resource.ExpectedSHA256 != "" {
+		got := hex.EncodeToString(hash.Sum(nil))
+		if got != resource.ExpectedSHA256 {
+			return fmt.Errorf("resource %q sha256 mismatch: expected %s, got %s", resource.SourcePath, resource.ExpectedSHA256, got)
+		}
+	}
 	return nil
 }

internal/erf/erf_test.go

@@ -2,9 +2,72 @@ package erf
 
 import (
 	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"os"
+	"path/filepath"
+	"strings"
 	"testing"
 )
 
+func writeTempPayload(t *testing.T, payload []byte) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "payload.bin")
+	if err := os.WriteFile(path, payload, 0o644); err != nil {
+		t.Fatalf("write payload: %v", err)
+	}
+	return path
+}
+
+func TestWriteRejectsSourcePathSHA256Mismatch(t *testing.T) {
+	payload := []byte("hello world")
+	path := writeTempPayload(t, payload)
+
+	archive := New("HAK ", []Resource{{
+		Name:           "asset",
+		Type:           0x0003,
+		SourcePath:     path,
+		Size:           int64(len(payload)),
+		ExpectedSHA256: strings.Repeat("a", 64),
+	}})
+
+	var buf bytes.Buffer
+	err := Write(&buf, archive)
+	if err == nil {
+		t.Fatal("expected sha256 mismatch error")
+	}
+	if !strings.Contains(err.Error(), "sha256 mismatch") {
+		t.Fatalf("error = %v, want sha256 mismatch", err)
+	}
+}
+
+func TestWriteAcceptsMatchingSourcePathSHA256(t *testing.T) {
+	payload := []byte("hello world")
+	path := writeTempPayload(t, payload)
+	sum := sha256.Sum256(payload)
+
+	archive := New("HAK ", []Resource{{
+		Name:           "asset",
+		Type:           0x0003,
+		SourcePath:     path,
+		Size:           int64(len(payload)),
+		ExpectedSHA256: hex.EncodeToString(sum[:]),
+	}})
+
+	var buf bytes.Buffer
+	if err := Write(&buf, archive); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	decoded, err := Read(bytes.NewReader(buf.Bytes()))
+	if err != nil {
+		t.Fatalf("read: %v", err)
+	}
+	if len(decoded.Resources) != 1 || string(decoded.Resources[0].Data) != string(payload) {
+		t.Fatalf("unexpected payload: %#v", decoded.Resources)
+	}
+}
+
 func TestArchiveRoundTrip(t *testing.T) {
 	archive := New("MOD ", []Resource{
 		{Name: "module", Type: 0x07DE, Data: []byte("ifo")},

internal/pipeline/build.go

@@ -106,11 +106,12 @@ type hakChunk struct {
 type ProgressFunc func(string)
 
 type BuildHAKOptions struct {
-	Progress           ProgressFunc
+	Progress             ProgressFunc
-	ArchiveNames       []string
+	ArchiveNames         []string
-	SourceManifestPath string
+	SourceManifestPath   string
-	SkipMusic          bool
+	ContentAddressedRoot string
-	MusicDatasetIDs    []string
+	SkipMusic            bool
+	MusicDatasetIDs      []string
 }
 
 func Build(p *project.Project) (BuildResult, error) {
@@ -196,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, opts.SkipMusic, opts.MusicDatasetIDs)
+	return planOrBuildHAKs(p, opts.Progress, true, opts)
 }
 
 func PlanHAKs(p *project.Project) (BuildResult, error) {
@@ -208,18 +209,18 @@ func PlanHAKsWithProgress(p *project.Project, progress ProgressFunc) (BuildResul
 }
 
 func PlanHAKsWithOptions(p *project.Project, opts BuildHAKOptions) (BuildResult, error) {
-	return planOrBuildHAKs(p, opts.Progress, false, opts.ArchiveNames, opts.SourceManifestPath, opts.SkipMusic, opts.MusicDatasetIDs)
+	return planOrBuildHAKs(p, opts.Progress, false, opts)
 }
 
 func buildHAKs(p *project.Project, progress ProgressFunc) (BuildResult, error) {
-	return planOrBuildHAKs(p, progress, true, nil, "", false, nil)
+	return planOrBuildHAKs(p, progress, true, BuildHAKOptions{})
 }
 
 func planHAKs(p *project.Project, progress ProgressFunc) (BuildResult, error) {
-	return planOrBuildHAKs(p, progress, false, nil, "", false, nil)
+	return planOrBuildHAKs(p, progress, false, BuildHAKOptions{})
 }
 
-func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bool, archiveNames []string, sourceManifestPath string, skipMusic bool, musicDatasetIDs []string) (result BuildResult, err error) {
+func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bool, opts BuildHAKOptions) (result BuildResult, err error) {
 	preserveExistingHAKs := p.EffectiveConfig().Build.KeepExistingHAKs || envBool("SOW_BUILD_HAKS_KEEP_EXISTING")
 
 	progressf(progress, "Validating project...")
@@ -227,15 +228,23 @@ func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bo
 		return BuildResult{}, err
 	}
 
+	directManifest, err := loadDirectSourceManifest(opts.SourceManifestPath)
+	if err != nil {
+		return BuildResult{}, err
+	}
+	if directManifest != nil {
+		return buildDirectHAKs(p, progress, writeArchives, directManifest, opts)
+	}
+
 	progressf(progress, "Collecting asset resources...")
-	allowedAssets, sourceManifest, err := loadSourceManifestAssetSet(sourceManifestPath)
+	allowedAssets, sourceManifest, err := loadSourceManifestAssetSet(opts.SourceManifestPath)
 	if err != nil {
 		return BuildResult{}, err
 	}
 	musicAssets := &preparedMusicAssets{SkipSourceRel: map[string]struct{}{}}
-	if !skipMusic {
+	if !opts.SkipMusic {
 		musicAssets, err = prepareMusicAssetsWithOptions(p, musicPrepareOptions{
-			datasetIDs: musicDatasetIDs,
+			datasetIDs: opts.MusicDatasetIDs,
 			write:      writeArchives,
 		})
 		if err != nil {
@@ -294,7 +303,7 @@ func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bo
 	if err != nil {
 		return BuildResult{}, err
 	}
-	chunks, err = filterHAKChunksByName(chunks, archiveNames)
+	chunks, err = filterHAKChunksByName(chunks, opts.ArchiveNames)
 	if err != nil {
 		return BuildResult{}, err
 	}
@@ -369,16 +378,8 @@ func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bo
 			if err := os.MkdirAll(filepath.Dir(hakPath), 0o755); err != nil {
 				return BuildResult{}, fmt.Errorf("create hak archive dir: %w", err)
 			}
-			hakOutput, err := os.Create(hakPath)
+			if err := writeHAKArchive(hakPath, resourceSlice(chunk.Assets)); err != nil {
-			if err != nil {
+				return BuildResult{}, err
-				return BuildResult{}, fmt.Errorf("create hak archive: %w", err)
-			}
-			if err := erf.Write(hakOutput, erf.New("HAK ", resourceSlice(chunk.Assets))); err != nil {
-				hakOutput.Close()
-				return BuildResult{}, fmt.Errorf("write hak archive: %w", err)
-			}
-			if err := hakOutput.Close(); err != nil {
-				return BuildResult{}, fmt.Errorf("close hak archive: %w", err)
 			}
 		}
 
@@ -408,6 +409,110 @@ func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bo
 	return result, nil
 }
 
+// buildDirectHAKs packages HAKs directly from the content-addressed source blob
+// cache. It skips music preparation, generated 2da discovery, git creation-time
+// lookups, LFS discovery, and any materialized asset tree scan.
+func buildDirectHAKs(p *project.Project, progress ProgressFunc, writeArchives bool, manifest *SourceBuildManifest, opts BuildHAKOptions) (BuildResult, error) {
+	progressf(progress, "Collecting asset resources...")
+	assetResources, err := collectDirectSourceResources(manifest, opts.ContentAddressedRoot)
+	if err != nil {
+		return BuildResult{}, err
+	}
+
+	result := BuildResult{HAKAssets: len(assetResources)}
+
+	progressf(progress, "Planning HAK chunks...")
+	chunks, err := chunksFromSourceManifest(assetResources, manifest.HAKs)
+	if err != nil {
+		return BuildResult{}, err
+	}
+	chunks, err = filterHAKChunksByName(chunks, opts.ArchiveNames)
+	if err != nil {
+		return BuildResult{}, err
+	}
+
+	buildManifest := BuildManifest{
+		ModuleHAKs: append([]string(nil), manifest.ModuleHAKs...),
+		HAKs:       make([]BuildManifestHAK, 0, len(chunks)),
+	}
+	for _, chunk := range chunks {
+		buildManifest.HAKs = append(buildManifest.HAKs, buildManifestEntry(chunk))
+	}
+
+	manifestPath := p.HAKManifestPath()
+	manifestBytes, err := json.MarshalIndent(buildManifest, "", "  ")
+	if err != nil {
+		return BuildResult{}, fmt.Errorf("marshal hak manifest: %w", err)
+	}
+	manifestBytes = append(manifestBytes, '\n')
+
+	if writeArchives {
+		progressf(progress, "Writing HAK archives...")
+		result.HAKSummary.Total = len(chunks)
+		result.HAKPaths = make([]string, 0, len(chunks))
+		for index, chunk := range chunks {
+			hakPath := p.HAKArchivePath(chunk.Name)
+			progressf(progress, fmt.Sprintf("Writing HAK %d/%d: %s (%d assets)", index+1, len(chunks), chunk.Name, len(chunk.Assets)))
+			if err := os.MkdirAll(filepath.Dir(hakPath), 0o755); err != nil {
+				return BuildResult{}, fmt.Errorf("create hak archive dir: %w", err)
+			}
+			if err := writeHAKArchive(hakPath, resourceSlice(chunk.Assets)); err != nil {
+				return BuildResult{}, err
+			}
+			result.HAKSummary.Written++
+			result.HAKSummary.Actions = append(result.HAKSummary.Actions, HAKArchiveAction{
+				Name:       chunk.Name,
+				AssetCount: len(chunk.Assets),
+				OutputPath: hakPath,
+			})
+			result.HAKPaths = append(result.HAKPaths, hakPath)
+		}
+	}
+
+	progressf(progress, "Writing HAK manifest...")
+	if err := os.MkdirAll(filepath.Dir(manifestPath), 0o755); err != nil {
+		return BuildResult{}, fmt.Errorf("create hak manifest dir: %w", err)
+	}
+	if err := os.WriteFile(manifestPath, manifestBytes, 0o644); err != nil {
+		return BuildResult{}, fmt.Errorf("write hak manifest: %w", err)
+	}
+	result.Manifest = manifestPath
+	return result, nil
+}
+
+// writeHAKArchive publishes a completed HAK atomically, so a failed write never
+// leaves a partial archive at the final path.
+func writeHAKArchive(hakPath string, resources []erf.Resource) error {
+	tmpPath := hakPath + ".tmp"
+	if err := os.Remove(tmpPath); err != nil && !errors.Is(err, os.ErrNotExist) {
+		return fmt.Errorf("remove stale temporary hak %s: %w", tmpPath, err)
+	}
+
+	output, err := os.OpenFile(tmpPath, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644)
+	if err != nil {
+		return fmt.Errorf("create temporary hak archive %s: %w", tmpPath, err)
+	}
+	if err := erf.Write(output, erf.New("HAK ", resources)); err != nil {
+		output.Close()
+		os.Remove(tmpPath)
+		return fmt.Errorf("write hak archive: %w", err)
+	}
+	if err := output.Sync(); err != nil {
+		output.Close()
+		os.Remove(tmpPath)
+		return fmt.Errorf("sync hak archive: %w", err)
+	}
+	if err := output.Close(); err != nil {
+		os.Remove(tmpPath)
+		return fmt.Errorf("close hak archive: %w", err)
+	}
+	if err := os.Rename(tmpPath, hakPath); err != nil {
+		os.Remove(tmpPath)
+		return fmt.Errorf("publish hak archive %s: %w", hakPath, err)
+	}
+	return nil
+}
+
 func writeAutogenManifestOutputs(progress ProgressFunc, manifests []topdata.ProducedAutogenManifest) error {
 	if len(manifests) == 0 {
 		return nil

internal/pipeline/pipeline_test.go

@@ -17,6 +17,35 @@ import (
 	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/project"
 )
 
+func TestBuildHAKsCleansFailedTemporaryArchive(t *testing.T) {
+	root := t.TempDir()
+	p := loadDirectProject(t, root)
+
+	blobs := filepath.Join(root, "blobs")
+	sha := strings.Repeat("a", 64)
+	writeBlobAt(t, blobs, sha, "wxyz")
+	manifestPath := writeDirectManifest(t, root,
+		map[string]SourceAsset{"core/a.tga": {SHA256: sha, SizeBytes: 4}},
+		[]string{"core/a.tga"})
+
+	tmpPath := filepath.Join(root, "build", "core_01.hak.tmp")
+	mustWriteFile(t, tmpPath, "stale partial archive")
+
+	_, err := BuildHAKsWithOptions(p, BuildHAKOptions{
+		SourceManifestPath:   manifestPath,
+		ContentAddressedRoot: blobs,
+	})
+	if err == nil {
+		t.Fatal("expected corrupt input to fail")
+	}
+	if _, err := os.Stat(filepath.Join(root, "build", "core_01.hak")); !errors.Is(err, os.ErrNotExist) {
+		t.Fatal("corrupt input must not leave a completed hak")
+	}
+	if _, err := os.Stat(tmpPath); !errors.Is(err, os.ErrNotExist) {
+		t.Fatal("failed build must clean temporary hak")
+	}
+}
+
 func TestBuildThenExtract(t *testing.T) {
 	root := t.TempDir()
 	mustMkdir(t, filepath.Join(root, "src"))

internal/pipeline/source_build_test.go

@@ -0,0 +1,249 @@
+package pipeline
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/buildinfo"
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/erf"
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/project"
+)
+
+const directProjectConfig = `{
+  "module": {
+    "name": "Test Module",
+    "resref": "testmod",
+    "hak_order": ["core_01"]
+  },
+  "paths": {
+    "source": "src",
+    "assets": "assets",
+    "build": "build"
+  }
+}
+`
+
+func writeBlobAt(t *testing.T, root, sha, content string) {
+	t.Helper()
+	dir := filepath.Join(root, "sha256", sha[0:2], sha[2:4])
+	mustMkdir(t, dir)
+	mustWriteFile(t, filepath.Join(dir, sha), content)
+}
+
+func writeBlob(t *testing.T, root string, payload []byte) string {
+	t.Helper()
+	sum := sha256.Sum256(payload)
+	sha := hex.EncodeToString(sum[:])
+	writeBlobAt(t, root, sha, string(payload))
+	return sha
+}
+
+func writeDirectManifest(t *testing.T, root string, sources map[string]SourceAsset, assets []string) string {
+	t.Helper()
+	manifest := SourceBuildManifest{
+		Schema:     1,
+		BuilderID:  buildinfo.String(),
+		ModuleHAKs: []string{"core_01"},
+		HAKs: []SourceManifestHAK{{
+			Name:     "core_01",
+			Group:    "core",
+			Priority: 1,
+			MaxBytes: 1 << 20,
+			Assets:   assets,
+		}},
+		AssetSources: sources,
+	}
+	raw, err := json.Marshal(manifest)
+	if err != nil {
+		t.Fatalf("marshal manifest: %v", err)
+	}
+	path := filepath.Join(root, "build-source-manifest.json")
+	mustWriteFile(t, path, string(raw))
+	return path
+}
+
+func loadDirectProject(t *testing.T, root string) *project.Project {
+	t.Helper()
+	mustWriteFile(t, filepath.Join(root, "nwn-tool.json"), directProjectConfig)
+	mustMkdir(t, filepath.Join(root, "build"))
+	p, err := project.Load(root)
+	if err != nil {
+		t.Fatalf("load project: %v", err)
+	}
+	return p
+}
+
+func TestBuildHAKsFromContentAddressedManifestWithoutAssetsTree(t *testing.T) {
+	root := t.TempDir()
+	p := loadDirectProject(t, root)
+
+	blobs := filepath.Join(root, "blobs")
+	payload := []byte("tga-payload-bytes")
+	sha := writeBlob(t, blobs, payload)
+	manifestPath := writeDirectManifest(t, root,
+		map[string]SourceAsset{"core/a.tga": {SHA256: sha, SizeBytes: int64(len(payload))}},
+		[]string{"core/a.tga"})
+
+	result, err := BuildHAKsWithOptions(p, BuildHAKOptions{
+		SourceManifestPath:   manifestPath,
+		ContentAddressedRoot: blobs,
+	})
+	if err != nil {
+		t.Fatalf("build direct haks: %v", err)
+	}
+	if result.HAKAssets != 1 {
+		t.Fatalf("hak assets = %d, want 1", result.HAKAssets)
+	}
+
+	if _, err := os.Stat(filepath.Join(root, "assets")); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("direct build must not materialize an assets tree (stat err = %v)", err)
+	}
+
+	hakPath := filepath.Join(root, "build", "core_01.hak")
+	raw, err := os.ReadFile(hakPath)
+	if err != nil {
+		t.Fatalf("read hak: %v", err)
+	}
+	archive, err := erf.Read(bytes.NewReader(raw))
+	if err != nil {
+		t.Fatalf("decode hak: %v", err)
+	}
+	if len(archive.Resources) != 1 {
+		t.Fatalf("hak resources = %d, want 1", len(archive.Resources))
+	}
+	if got := string(archive.Resources[0].Data); got != string(payload) {
+		t.Fatalf("resource payload = %q, want %q", got, payload)
+	}
+	if archive.Resources[0].Name != "a" {
+		t.Fatalf("resref = %q, want a", archive.Resources[0].Name)
+	}
+}
+
+func TestBuildHAKsFromContentAddressedManifestRejectsMissingRoot(t *testing.T) {
+	root := t.TempDir()
+	p := loadDirectProject(t, root)
+
+	blobs := filepath.Join(root, "blobs")
+	payload := []byte("tga-payload-bytes")
+	sha := writeBlob(t, blobs, payload)
+	manifestPath := writeDirectManifest(t, root,
+		map[string]SourceAsset{"core/a.tga": {SHA256: sha, SizeBytes: int64(len(payload))}},
+		[]string{"core/a.tga"})
+
+	_, err := BuildHAKsWithOptions(p, BuildHAKOptions{SourceManifestPath: manifestPath})
+	if err == nil {
+		t.Fatal("expected failure when content-addressed root is missing")
+	}
+}
+
+func TestBuildHAKsFromContentAddressedManifestRejectsMissingBlob(t *testing.T) {
+	root := t.TempDir()
+	p := loadDirectProject(t, root)
+
+	blobs := filepath.Join(root, "blobs")
+	sha := strings.Repeat("b", 64)
+	manifestPath := writeDirectManifest(t, root,
+		map[string]SourceAsset{"core/a.tga": {SHA256: sha, SizeBytes: 4}},
+		[]string{"core/a.tga"})
+
+	_, err := BuildHAKsWithOptions(p, BuildHAKOptions{
+		SourceManifestPath:   manifestPath,
+		ContentAddressedRoot: blobs,
+	})
+	if err == nil {
+		t.Fatal("expected failure for missing source blob")
+	}
+}
+
+func TestBuildHAKsFromContentAddressedManifestRejectsCorruptBlob(t *testing.T) {
+	root := t.TempDir()
+	p := loadDirectProject(t, root)
+
+	blobs := filepath.Join(root, "blobs")
+	declared := sha256.Sum256([]byte("abcd"))
+	sha := hex.EncodeToString(declared[:])
+	// Same length, different bytes: size check passes, content hash mismatches.
+	writeBlobAt(t, blobs, sha, "wxyz")
+	manifestPath := writeDirectManifest(t, root,
+		map[string]SourceAsset{"core/a.tga": {SHA256: sha, SizeBytes: 4}},
+		[]string{"core/a.tga"})
+
+	_, err := BuildHAKsWithOptions(p, BuildHAKOptions{
+		SourceManifestPath:   manifestPath,
+		ContentAddressedRoot: blobs,
+	})
+	if err == nil {
+		t.Fatal("expected sha256 mismatch failure for corrupt blob")
+	}
+	if !strings.Contains(err.Error(), "sha256 mismatch") {
+		t.Fatalf("error = %v, want sha256 mismatch", err)
+	}
+	if _, statErr := os.Stat(filepath.Join(root, "build", "core_01.hak")); !errors.Is(statErr, os.ErrNotExist) {
+		t.Fatalf("corrupt build must not leave a completed hak (stat err = %v)", statErr)
+	}
+}
+
+func TestLegacySourceManifestStillBuildsFromAssetsTree(t *testing.T) {
+	root := t.TempDir()
+	mustMkdir(t, filepath.Join(root, "src", "module"))
+	mustMkdir(t, filepath.Join(root, "assets", "core"))
+	mustMkdir(t, filepath.Join(root, "build"))
+	mustWriteFile(t, filepath.Join(root, "nwn-tool.json"), `{
+  "module": {"name": "Test Module", "resref": "testmod", "hak_order": ["group:core"]},
+  "paths": {"source": "src", "assets": "assets", "build": "build"},
+  "haks": [{"name": "core", "priority": 1, "include": ["core/**"]}]
+}
+`)
+	mustWriteFile(t, filepath.Join(root, "src", "module", "module.ifo.json"), `{
+  "file_type": "IFO ",
+  "file_version": "V3.2",
+  "root": {"struct_type": 0, "fields": [
+    {"label": "Mod_Name", "type": "CExoString", "value": "Test Module"},
+    {"label": "Mod_HakList", "type": "List", "value": []}
+  ]}
+}
+`)
+	mustWriteFile(t, filepath.Join(root, "assets", "core", "a.tga"), strings.Repeat("a", 16))
+	mustWriteFile(t, filepath.Join(root, "assets", "core", "b.tga"), strings.Repeat("b", 16))
+
+	manifestPath := filepath.Join(root, "legacy-source-manifest.json")
+	mustWriteFile(t, manifestPath, `{
+  "module_haks": ["core"],
+  "haks": [{"name": "core", "group": "core", "priority": 1, "assets": ["core/a.tga", "core/b.tga"]}]
+}
+`)
+
+	p, err := project.Load(root)
+	if err != nil {
+		t.Fatalf("load project: %v", err)
+	}
+	if err := p.Scan(); err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+
+	result, err := BuildHAKsWithOptions(p, BuildHAKOptions{SourceManifestPath: manifestPath})
+	if err != nil {
+		t.Fatalf("legacy build: %v", err)
+	}
+	if len(result.HAKPaths) != 1 {
+		t.Fatalf("hak paths = %d, want 1", len(result.HAKPaths))
+	}
+	raw, err := os.ReadFile(filepath.Join(root, "build", "core.hak"))
+	if err != nil {
+		t.Fatalf("read legacy hak: %v", err)
+	}
+	archive, err := erf.Read(bytes.NewReader(raw))
+	if err != nil {
+		t.Fatalf("decode legacy hak: %v", err)
+	}
+	if len(archive.Resources) != 2 {
+		t.Fatalf("legacy hak resources = %d, want 2", len(archive.Resources))
+	}
+}

internal/pipeline/source_manifest.go

@@ -0,0 +1,232 @@
+package pipeline
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	pathpkg "path"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"strings"
+
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/buildinfo"
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/erf"
+)
+
+// SourceAsset is one content-addressed source blob referenced by a direct source
+// manifest. The blob is resolved by sha256 under the content-addressed root.
+type SourceAsset struct {
+	SHA256    string `json:"sha256"`
+	SizeBytes int64  `json:"size_bytes"`
+}
+
+// SourceManifestHAK describes one output HAK and the logical asset paths it packs.
+type SourceManifestHAK struct {
+	Name     string   `json:"name"`
+	Group    string   `json:"group"`
+	Priority int      `json:"priority"`
+	MaxBytes int64    `json:"max_bytes"`
+	Optional bool     `json:"optional,omitempty"`
+	Assets   []string `json:"assets"`
+	BuildKey string   `json:"build_key"`
+}
+
+// SourceBuildManifest is the generated, content-addressed input to a HAK build.
+// It carries asset_sources, so Crucible reads source bytes directly from the blob
+// cache without scanning a materialized asset tree.
+type SourceBuildManifest struct {
+	Schema       int                    `json:"schema"`
+	BuilderID    string                 `json:"builder_id"`
+	ModuleHAKs   []string               `json:"module_haks"`
+	HAKs         []SourceManifestHAK    `json:"haks"`
+	AssetSources map[string]SourceAsset `json:"asset_sources"`
+}
+
+var sha256Pattern = regexp.MustCompile(`^[0-9a-f]{64}$`)
+
+// hasAssetSources reports whether raw JSON carries the direct content-addressed
+// schema. A legacy BuildManifest has no asset_sources object.
+func hasAssetSources(raw []byte) bool {
+	var header struct {
+		AssetSources map[string]json.RawMessage `json:"asset_sources"`
+	}
+	if err := json.Unmarshal(raw, &header); err != nil {
+		return false
+	}
+	return header.AssetSources != nil
+}
+
+func loadSourceBuildManifest(path string) (*SourceBuildManifest, error) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("read source manifest %s: %w", path, err)
+	}
+	var manifest SourceBuildManifest
+	if err := json.Unmarshal(raw, &manifest); err != nil {
+		return nil, fmt.Errorf("parse source manifest %s: %w", path, err)
+	}
+	return &manifest, nil
+}
+
+func validateDirectSourceManifest(manifest *SourceBuildManifest) error {
+	if manifest.Schema != 1 {
+		return fmt.Errorf("unsupported source manifest schema %d", manifest.Schema)
+	}
+	if manifest.BuilderID != buildinfo.String() {
+		return fmt.Errorf("source manifest builder_id %q does not match builder %q", manifest.BuilderID, buildinfo.String())
+	}
+	if len(manifest.ModuleHAKs) == 0 {
+		return fmt.Errorf("source manifest module_haks is empty")
+	}
+
+	referenced := make(map[string]struct{}, len(manifest.AssetSources))
+	for _, hak := range manifest.HAKs {
+		if strings.TrimSpace(hak.Name) == "" {
+			return fmt.Errorf("source manifest hak has empty name")
+		}
+		for _, rel := range hak.Assets {
+			if !validLogicalAssetPath(rel) {
+				return fmt.Errorf("source manifest hak %s has invalid asset path %q", hak.Name, rel)
+			}
+			if _, dup := referenced[rel]; dup {
+				return fmt.Errorf("source manifest asset %q referenced by more than one hak", rel)
+			}
+			referenced[rel] = struct{}{}
+			source, ok := manifest.AssetSources[rel]
+			if !ok {
+				return fmt.Errorf("source manifest hak %s asset %q has no asset_sources entry", hak.Name, rel)
+			}
+			if !sha256Pattern.MatchString(source.SHA256) {
+				return fmt.Errorf("source manifest asset %q has invalid sha256 %q", rel, source.SHA256)
+			}
+			if source.SizeBytes < 0 {
+				return fmt.Errorf("source manifest asset %q has negative size %d", rel, source.SizeBytes)
+			}
+		}
+	}
+
+	for rel := range manifest.AssetSources {
+		if !validLogicalAssetPath(rel) {
+			return fmt.Errorf("source manifest asset_sources has invalid path %q", rel)
+		}
+		if _, ok := referenced[rel]; !ok {
+			return fmt.Errorf("source manifest asset_sources entry %q is not referenced by any hak", rel)
+		}
+	}
+	return nil
+}
+
+func validLogicalAssetPath(path string) bool {
+	if path == "" || filepath.IsAbs(path) || strings.Contains(path, `\`) {
+		return false
+	}
+	clean := pathpkg.Clean(path)
+	return clean == path && clean != "." && clean != ".." &&
+		!strings.HasPrefix(clean, "../")
+}
+
+func contentAddressedBlobPath(root, sha string) (string, error) {
+	if strings.TrimSpace(root) == "" {
+		return "", fmt.Errorf("content-addressed root is required")
+	}
+	if !sha256Pattern.MatchString(sha) {
+		return "", fmt.Errorf("invalid content-addressed sha256 %q", sha)
+	}
+	return filepath.Join(root, "sha256", sha[0:2], sha[2:4], sha), nil
+}
+
+// loadDirectSourceManifest returns a parsed direct source manifest when path
+// points at a content-addressed manifest. It returns (nil, nil) for an empty
+// path or a legacy manifest without asset_sources, so the caller falls through
+// to the legacy path-backed build.
+func loadDirectSourceManifest(path string) (*SourceBuildManifest, error) {
+	if strings.TrimSpace(path) == "" {
+		return nil, nil
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("read source manifest %s: %w", path, err)
+	}
+	if !hasAssetSources(raw) {
+		return nil, nil
+	}
+	var manifest SourceBuildManifest
+	if err := json.Unmarshal(raw, &manifest); err != nil {
+		return nil, fmt.Errorf("parse source manifest %s: %w", path, err)
+	}
+	return &manifest, nil
+}
+
+// collectDirectSourceResources resolves each manifest-named blob under contentRoot
+// and produces sorted asset resources that stream from the blob cache with their
+// expected SHA-256. It never scans a materialized asset tree.
+func collectDirectSourceResources(manifest *SourceBuildManifest, contentRoot string) ([]assetResource, error) {
+	if err := validateDirectSourceManifest(manifest); err != nil {
+		return nil, err
+	}
+	if strings.TrimSpace(contentRoot) == "" {
+		return nil, fmt.Errorf("content-addressed source manifest requires --content-addressed-root")
+	}
+
+	resources := make([]assetResource, 0, len(manifest.AssetSources))
+	for _, hak := range manifest.HAKs {
+		for _, logicalPath := range hak.Assets {
+			source := manifest.AssetSources[logicalPath]
+			extension := strings.TrimPrefix(strings.ToLower(filepath.Ext(logicalPath)), ".")
+			resourceType, ok := erf.HAKResourceTypeForExtension(extension)
+			if !ok {
+				return nil, fmt.Errorf("unsupported HAK resource extension %q for %s", filepath.Ext(logicalPath), logicalPath)
+			}
+			resref := strings.ToLower(strings.TrimSuffix(filepath.Base(logicalPath), filepath.Ext(logicalPath)))
+
+			blobPath, err := contentAddressedBlobPath(contentRoot, source.SHA256)
+			if err != nil {
+				return nil, err
+			}
+			info, err := os.Stat(blobPath)
+			if err != nil {
+				return nil, fmt.Errorf("missing source blob for %s: %w", logicalPath, err)
+			}
+			if info.Size() != source.SizeBytes {
+				return nil, fmt.Errorf("source blob size mismatch for %s: expected %d, got %d", logicalPath, source.SizeBytes, info.Size())
+			}
+
+			resource := erf.Resource{
+				Name:           resref,
+				Type:           resourceType,
+				SourcePath:     blobPath,
+				Size:           source.SizeBytes,
+				ExpectedSHA256: source.SHA256,
+			}
+			resources = append(resources, assetResource{
+				Rel:       logicalPath,
+				Resource:  resource,
+				Size:      erf.ArchiveSize([]erf.Resource{resource}),
+				ContentID: "sha256:" + source.SHA256,
+			})
+		}
+	}
+
+	slices.SortFunc(resources, func(a, b assetResource) int {
+		return compareResourceKeys(a.Resource, b.Resource)
+	})
+	return resources, nil
+}
+
+// chunksFromSourceManifest converts direct manifest HAK entries into build chunks
+// reusing the legacy manifest chunker.
+func chunksFromSourceManifest(assets []assetResource, entries []SourceManifestHAK) ([]hakChunk, error) {
+	converted := make([]BuildManifestHAK, len(entries))
+	for index, entry := range entries {
+		converted[index] = BuildManifestHAK{
+			Name:     entry.Name,
+			Group:    entry.Group,
+			Priority: entry.Priority,
+			MaxBytes: entry.MaxBytes,
+			Optional: entry.Optional,
+			Assets:   entry.Assets,
+		}
+	}
+	return chunksFromManifest(assets, converted)
+}

internal/pipeline/source_manifest_test.go

@@ -0,0 +1,160 @@
+package pipeline
+
+import (
+	"encoding/json"
+	"path/filepath"
+	"testing"
+
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/buildinfo"
+)
+
+const validAsset = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+
+// directManifestFixture returns a minimal valid direct source manifest using the
+// running builder identity, so validation does not reject it on builder mismatch.
+func directManifestFixture() *SourceBuildManifest {
+	return &SourceBuildManifest{
+		Schema:     1,
+		BuilderID:  buildinfo.String(),
+		ModuleHAKs: []string{"core_01"},
+		HAKs: []SourceManifestHAK{
+			{
+				Name:     "core_01",
+				Group:    "core",
+				Priority: 1,
+				MaxBytes: 1024,
+				Assets:   []string{"core/a.tga"},
+			},
+		},
+		AssetSources: map[string]SourceAsset{
+			"core/a.tga": {SHA256: validAsset, SizeBytes: 4},
+		},
+	}
+}
+
+func writeManifestFixture(t *testing.T, manifest *SourceBuildManifest) string {
+	t.Helper()
+	raw, err := json.Marshal(manifest)
+	if err != nil {
+		t.Fatalf("marshal fixture: %v", err)
+	}
+	path := filepath.Join(t.TempDir(), "build-source-manifest.json")
+	mustWriteFile(t, path, string(raw))
+	return path
+}
+
+func TestLoadSourceBuildManifestDirect(t *testing.T) {
+	path := writeManifestFixture(t, directManifestFixture())
+
+	manifest, err := loadSourceBuildManifest(path)
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if manifest.Schema != 1 {
+		t.Fatalf("schema = %d, want 1", manifest.Schema)
+	}
+	if manifest.BuilderID != buildinfo.String() {
+		t.Fatalf("builder_id = %q, want %q", manifest.BuilderID, buildinfo.String())
+	}
+	if len(manifest.HAKs) != 1 || manifest.HAKs[0].Name != "core_01" {
+		t.Fatalf("unexpected haks: %#v", manifest.HAKs)
+	}
+	source, ok := manifest.AssetSources["core/a.tga"]
+	if !ok || source.SHA256 != validAsset || source.SizeBytes != 4 {
+		t.Fatalf("unexpected asset source: %#v", manifest.AssetSources)
+	}
+	if err := validateDirectSourceManifest(manifest); err != nil {
+		t.Fatalf("validate valid manifest: %v", err)
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsUnsupportedSchema(t *testing.T) {
+	manifest := directManifestFixture()
+	manifest.Schema = 2
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected schema rejection")
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsBadSHA(t *testing.T) {
+	manifest := directManifestFixture()
+	manifest.AssetSources["core/a.tga"] = SourceAsset{SHA256: "NOTHEX", SizeBytes: 4}
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected bad sha rejection")
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsNegativeSize(t *testing.T) {
+	manifest := directManifestFixture()
+	manifest.AssetSources["core/a.tga"] = SourceAsset{SHA256: validAsset, SizeBytes: -1}
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected negative size rejection")
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsMissingSource(t *testing.T) {
+	manifest := directManifestFixture()
+	delete(manifest.AssetSources, "core/a.tga")
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected missing source rejection")
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsUnusedSource(t *testing.T) {
+	manifest := directManifestFixture()
+	manifest.AssetSources["core/orphan.tga"] = SourceAsset{SHA256: validAsset, SizeBytes: 4}
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected unused source rejection")
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsDuplicateAssetAcrossHAKs(t *testing.T) {
+	manifest := directManifestFixture()
+	manifest.HAKs = append(manifest.HAKs, SourceManifestHAK{
+		Name:     "core_02",
+		Group:    "core",
+		Priority: 1,
+		MaxBytes: 1024,
+		Assets:   []string{"core/a.tga"},
+	})
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected duplicate-asset rejection")
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsTraversalPath(t *testing.T) {
+	manifest := directManifestFixture()
+	manifest.HAKs[0].Assets = []string{"../escape.tga"}
+	manifest.AssetSources = map[string]SourceAsset{
+		"../escape.tga": {SHA256: validAsset, SizeBytes: 4},
+	}
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected traversal rejection")
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsBuilderMismatch(t *testing.T) {
+	manifest := directManifestFixture()
+	manifest.BuilderID = "crucible deadbeef"
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected builder mismatch rejection")
+	}
+}
+
+func TestContentAddressedBlobPath(t *testing.T) {
+	root := "/var/cache/blobs"
+	got, err := contentAddressedBlobPath(root, validAsset)
+	if err != nil {
+		t.Fatalf("blob path: %v", err)
+	}
+	want := filepath.Join(root, "sha256", "aa", "aa", validAsset)
+	if got != want {
+		t.Fatalf("blob path = %q, want %q", got, want)
+	}
+	if _, err := contentAddressedBlobPath(root, "NOTHEX"); err == nil {
+		t.Fatal("expected invalid sha rejection")
+	}
+	if _, err := contentAddressedBlobPath("", validAsset); err == nil {
+		t.Fatal("expected empty root rejection")
+	}
+}

internal/topdata/autogen.go

@@ -3,6 +3,7 @@ package topdata
 import (
 	"bytes"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -16,6 +17,19 @@ import (
 
 const autogenManifestCacheMaxAge = time.Hour
 
+// errAutogenManifestUnavailable marks a released autogen manifest that could not
+// be located or fetched (network failure, missing release/asset, empty payload,
+// or an undeterminable sow-assets repo). It is deliberately distinct from an
+// asset that was found but reports a row removed: for an optional consumer this
+// sentinel triggers a fail-open path that *preserves* the consumer's existing
+// pinned lock entries instead of pruning them, so StrRef/row IDs are not
+// reshuffled while the asset source is merely temporarily out of reach.
+var errAutogenManifestUnavailable = errors.New("autogen manifest unavailable")
+
+func unavailableAutogenManifest(err error) error {
+	return fmt.Errorf("%w: %w", errAutogenManifestUnavailable, err)
+}
+
 type autogenManifest struct {
 	ID                string                           `json:"id"`
 	Repo              string                           `json:"repo"`
@@ -61,9 +75,18 @@ func applyAutogenConsumers(p *project.Project, collected []nativeCollectedDatase
 		}
 		manifest, err := resolveAutogenConsumerManifest(p, consumer, progress)
 		if err != nil {
-			if consumer.Optional && isIgnorableOptionalAutogenError(err) {
+			if consumer.Optional && errors.Is(err, errAutogenManifestUnavailable) {
+				// Fail open: the asset manifest is merely unreachable, not
+				// authoritatively empty. Build without its rows, but keep the
+				// consumer's already-pinned lock entries so their IDs are not
+				// freed and reshuffled on a later build once the asset returns.
+				preserved, perr := preserveAutogenConsumerLockEntries(result, consumer)
+				if perr != nil {
+					return nil, perr
+				}
+				result = preserved
 				if progress != nil {
-					progress(fmt.Sprintf("Skipping optional autogen consumer %s: %v", consumer.ID, err))
+					progress(fmt.Sprintf("Autogen consumer %s: released manifest unavailable (%v); preserving existing lock entries, generating no new rows", consumer.ID, err))
 				}
 				continue
 			}
@@ -90,32 +113,115 @@ func applyAutogenConsumers(p *project.Project, collected []nativeCollectedDatase
 
 func autogenConsumerTargetsCollectedDataset(collected []nativeCollectedDataset, consumer project.AutogenConsumerConfig) bool {
 	for _, dataset := range collected {
-		switch consumer.Mode {
+		if autogenConsumerTargetsDataset(dataset, consumer) {
-		case "parts_rows":
+			return true
-			if isAutogenEligiblePartsDataset(dataset) {
-				return true
-			}
-		case "accessory_visualeffects":
-			if dataset.Dataset.Name == "visualeffects" {
-				return true
-			}
-		case "cachedmodels_rows":
-			if dataset.Dataset.Name == "cachedmodels" {
-				return true
-			}
 		}
 	}
 	return false
 }
 
-func isIgnorableOptionalAutogenError(err error) bool {
+// preserveAutogenConsumerLockEntries restores the lock keys that an autogen
-	if err == nil {
+// consumer owns from the on-disk lockfile back into the in-memory dataset,
+// reusing this build's already-collected (and pruned) state. It is called only
+// when the consumer's released manifest is unavailable, so the rows themselves
+// are not regenerated; we just keep the key->ID pins alive. Keys are matched
+// against the consumer's own naming policy so unrelated (authored) rows that were
+// legitimately removed are not resurrected.
+func preserveAutogenConsumerLockEntries(collected []nativeCollectedDataset, consumer project.AutogenConsumerConfig) ([]nativeCollectedDataset, error) {
+	matches := autogenConsumerManagedLockKeyMatcher(consumer)
+	if matches == nil {
+		// No managed-key matcher for this mode: nothing safe to preserve.
+		return collected, nil
+	}
+
+	result := append([]nativeCollectedDataset(nil), collected...)
+	for i, dataset := range result {
+		if !autogenConsumerTargetsDataset(dataset, consumer) {
+			continue
+		}
+		if strings.TrimSpace(dataset.Dataset.LockPath) == "" {
+			continue
+		}
+		onDisk, err := loadLockfile(dataset.Dataset.LockPath)
+		if err != nil {
+			// No readable lockfile means there is nothing pinned to preserve.
+			continue
+		}
+		lockData := dataset.LockData
+		if lockData == nil {
+			lockData = map[string]int{}
+		}
+		restored := 0
+		for key, rowID := range onDisk {
+			if _, present := lockData[key]; present {
+				continue
+			}
+			if !matches(key) {
+				continue
+			}
+			lockData[key] = rowID
+			restored++
+		}
+		if restored == 0 {
+			continue
+		}
+		result[i].LockData = lockData
+		result[i].LockModified = !lockDataEqual(onDisk, lockData)
+	}
+	return result, nil
+}
+
+// autogenConsumerManagedLockKeyMatcher returns a predicate identifying the lock
+// keys an autogen consumer is responsible for, or nil for modes whose keys we
+// cannot scope precisely (in which case preservation is skipped rather than
+// risk resurrecting unrelated keys).
+func autogenConsumerManagedLockKeyMatcher(consumer project.AutogenConsumerConfig) func(string) bool {
+	switch consumer.Mode {
+	case "accessory_visualeffects":
+		policy := resolveHeadVisualeffectsPolicy(consumer, nil)
+		delimiter := policy.Delimiter
+		if delimiter == "" {
+			delimiter = "/"
+		}
+		prefix := "visualeffects:"
+		groups := make(map[string]struct{}, len(policy.Groups))
+		for group, groupPolicy := range policy.Groups {
+			token := applyHeadVisualeffectCase(headVisualeffectGroupToken(group, groupPolicy, policy), policy)
+			if strings.TrimSpace(token) != "" {
+				groups[token] = struct{}{}
+			}
+		}
+		if len(groups) == 0 {
+			return nil
+		}
+		return func(key string) bool {
+			if !strings.HasPrefix(key, prefix) {
+				return false
+			}
+			rest := key[len(prefix):]
+			idx := strings.Index(rest, delimiter)
+			if idx <= 0 {
+				return false
+			}
+			_, ok := groups[rest[:idx]]
+			return ok
+		}
+	default:
+		return nil
+	}
+}
+
+func autogenConsumerTargetsDataset(dataset nativeCollectedDataset, consumer project.AutogenConsumerConfig) bool {
+	switch consumer.Mode {
+	case "parts_rows":
+		return isAutogenEligiblePartsDataset(dataset)
+	case "accessory_visualeffects":
+		return dataset.Dataset.Name == "visualeffects"
+	case "cachedmodels_rows":
+		return dataset.Dataset.Name == "cachedmodels"
+	default:
 		return false
 	}
-	message := err.Error()
-	return strings.Contains(message, "HTTP 404") ||
-		strings.Contains(message, "not found") ||
-		strings.Contains(message, "entries is empty")
 }
 
 func resolveAutogenConsumerManifest(p *project.Project, consumer project.AutogenConsumerConfig, progress func(string)) (*autogenManifest, error) {
@@ -366,14 +472,14 @@ func resolveReleasedAutogenManifest(p *project.Project, consumer project.Autogen
 
 	spec, err := deriveSowAssetsRepoSpec(p)
 	if err != nil {
-		return nil, err
+		return nil, unavailableAutogenManifest(err)
 	}
 	manifestURL, err := resolveAutogenManifestAssetURL(spec, consumer.Manifest.ReleaseTag, consumer.Manifest.AssetName)
 	if err != nil {
 		if consumer.Mode == "parts_rows" {
-			return nil, fmt.Errorf("%s", strings.Replace(err.Error(), "autogen manifest", "parts manifest", 1))
+			return nil, unavailableAutogenManifest(fmt.Errorf("%s", strings.Replace(err.Error(), "autogen manifest", "parts manifest", 1)))
 		}
-		return nil, err
+		return nil, unavailableAutogenManifest(err)
 	}
 	if progress != nil {
 		progress(fmt.Sprintf("Fetching released autogen manifest from %s...", manifestURL))
@@ -381,9 +487,9 @@ func resolveReleasedAutogenManifest(p *project.Project, consumer project.Autogen
 	manifest, err := fetchAutogenManifest(manifestURL)
 	if err != nil {
 		if consumer.Mode == "parts_rows" {
-			return nil, fmt.Errorf("%s", strings.Replace(err.Error(), "autogen manifest", "parts manifest", 1))
+			return nil, unavailableAutogenManifest(fmt.Errorf("%s", strings.Replace(err.Error(), "autogen manifest", "parts manifest", 1)))
 		}
-		return nil, err
+		return nil, unavailableAutogenManifest(err)
 	}
 	if manifest.ID != "" && manifest.ID != consumer.Producer {
 		return nil, fmt.Errorf("autogen manifest %s declared id %q, expected %q", consumer.Manifest.AssetName, manifest.ID, consumer.Producer)

internal/topdata/autogen_preserve_test.go

@@ -0,0 +1,109 @@
+package topdata
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/project"
+)
+
+// When an optional autogen consumer's released manifest cannot be fetched, the
+// build must fail open: it keeps the consumer's already-pinned lock entries
+// (so their IDs are not freed and reshuffled later) and generates no new rows.
+func TestApplyAutogenConsumersPreservesLockEntriesWhenManifestUnavailable(t *testing.T) {
+	root := testProjectRoot(t)
+
+	// 404 for every request → released manifest is unavailable (not empty).
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.NotFound(w, r)
+	}))
+	t.Cleanup(srv.Close)
+	t.Setenv("SOW_ASSETS_SERVER_URL", srv.URL)
+	t.Setenv("SOW_ASSETS_REPO", "ShadowsOverWestgate/sow-assets")
+
+	p := testProject(root)
+	p.Config.Autogen.Consumers = []project.AutogenConsumerConfig{
+		{
+			ID:       "accessory_visualeffects",
+			Producer: "accessory_visualeffects",
+			Dataset:  "visualeffects",
+			Mode:     "accessory_visualeffects",
+			Optional: true,
+			Root:     "vfxs",
+			Include:  []string{"head_accessories/**/*.mdl"},
+			Derive:   project.AutogenDeriveConfig{Kind: "model_stem", GroupFrom: "first_path_segment"},
+			Manifest: project.AutogenManifestConfig{ReleaseTag: "head-vfx-manifest-current", AssetName: "sow-accessory-vfx-manifest.json", CacheName: "sow-accessory-vfx-manifest.json"},
+		},
+	}
+
+	// On-disk lock pins an autogen-owned accessory key plus an authored key.
+	lockPath := filepath.Join(root, "visualeffects-lock.json")
+	writeFile(t, lockPath, `{"visualeffects:existing":17,"visualeffects:head_accessories/hat/bandana":10101}`+"\n")
+
+	// Simulate post-prune collected state: the accessory key has already been
+	// dropped from in-memory LockData (as pruneLockDataToActiveRows would do).
+	collected := []nativeCollectedDataset{
+		{
+			Dataset:  nativeDataset{Name: "visualeffects", Kind: nativeDatasetBase, LockPath: lockPath},
+			Columns:  []string{"Label"},
+			Rows:     []map[string]any{{"id": 17, "key": "visualeffects:existing"}},
+			LockData: map[string]int{"visualeffects:existing": 17},
+		},
+	}
+
+	got, err := applyAutogenConsumers(p, collected, nil)
+	if err != nil {
+		t.Fatalf("expected fail-open build, got error: %v", err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("expected one dataset, got %d", len(got))
+	}
+
+	// The pinned accessory id must survive with its exact value (no jumble).
+	if id, ok := got[0].LockData["visualeffects:head_accessories/hat/bandana"]; !ok || id != 10101 {
+		t.Fatalf("expected preserved accessory lock id 10101, got %v (present=%v) lock=%#v", id, ok, got[0].LockData)
+	}
+	// The authored key is untouched.
+	if id, ok := got[0].LockData["visualeffects:existing"]; !ok || id != 17 {
+		t.Fatalf("expected authored key retained at 17, got %#v", got[0].LockData)
+	}
+	// No row is generated for the unavailable accessory entry.
+	for _, row := range got[0].Rows {
+		if key, _ := row["key"].(string); key == "visualeffects:head_accessories/hat/bandana" {
+			t.Fatalf("expected no generated row while manifest unavailable, got %#v", row)
+		}
+	}
+}
+
+// A key that is NOT owned by the consumer (an authored row legitimately removed)
+// must not be resurrected by the preservation path.
+func TestPreserveAutogenConsumerLockEntriesIgnoresUnownedKeys(t *testing.T) {
+	root := testProjectRoot(t)
+	lockPath := filepath.Join(root, "visualeffects-lock.json")
+	writeFile(t, lockPath, `{"visualeffects:retired_authored":3,"visualeffects:head_accessories/hat/bandana":10101}`+"\n")
+
+	consumer := project.AutogenConsumerConfig{
+		ID:      "accessory_visualeffects",
+		Dataset: "visualeffects",
+		Mode:    "accessory_visualeffects",
+	}
+	collected := []nativeCollectedDataset{
+		{
+			Dataset:  nativeDataset{Name: "visualeffects", Kind: nativeDatasetBase, LockPath: lockPath},
+			LockData: map[string]int{},
+		},
+	}
+
+	got, err := preserveAutogenConsumerLockEntries(collected, consumer)
+	if err != nil {
+		t.Fatalf("preserveAutogenConsumerLockEntries failed: %v", err)
+	}
+	if _, ok := got[0].LockData["visualeffects:head_accessories/hat/bandana"]; !ok {
+		t.Fatalf("expected owned accessory key preserved, got %#v", got[0].LockData)
+	}
+	if _, ok := got[0].LockData["visualeffects:retired_authored"]; ok {
+		t.Fatalf("expected unowned authored key NOT resurrected, got %#v", got[0].LockData)
+	}
+}

internal/topdata/damagetypes_registry.go

@@ -21,16 +21,20 @@ type damagetypesRegistry struct {
 	Types    []map[string]any
 }
 
-func collectGeneratedRegistryDatasets(dataDir string) ([]nativeCollectedDataset, error) {
+// collectGeneratedRegistryDatasets projects the registry datasets. When
-	itempropsDatasets, err := collectItempropsRegistryDatasets(dataDir)
+// persistLocks is true (the build pipeline) newly allocated ids are written
+// back to the source lockfiles; when false (validation, discovery, queries)
+// collection is read-only and never touches the source tree.
+func collectGeneratedRegistryDatasets(dataDir string, persistLocks bool) ([]nativeCollectedDataset, error) {
+	itempropsDatasets, err := collectItempropsRegistryDatasets(dataDir, persistLocks)
 	if err != nil {
 		return nil, err
 	}
-	damagetypeDatasets, err := collectDamagetypesRegistryDatasets(dataDir)
+	damagetypeDatasets, err := collectDamagetypesRegistryDatasets(dataDir, persistLocks)
 	if err != nil {
 		return nil, err
 	}
-	racialtypesDatasets, err := collectRacialtypesRegistryDatasets(dataDir)
+	racialtypesDatasets, err := collectRacialtypesRegistryDatasets(dataDir, persistLocks)
 	if err != nil {
 		return nil, err
 	}
@@ -70,7 +74,7 @@ func loadDamagetypesRegistry(dataDir string) (*damagetypesRegistry, error) {
 	}, nil
 }
 
-func collectDamagetypesRegistryDatasets(dataDir string) ([]nativeCollectedDataset, error) {
+func collectDamagetypesRegistryDatasets(dataDir string, persistLocks bool) ([]nativeCollectedDataset, error) {
 	registry, err := loadDamagetypesRegistry(dataDir)
 	if err != nil {
 		return nil, err
@@ -83,7 +87,7 @@ func collectDamagetypesRegistryDatasets(dataDir string) ([]nativeCollectedDatase
 	if err != nil {
 		return nil, err
 	}
-	if lockModified {
+	if lockModified && persistLocks {
 		if err := saveLockfile(registry.LockPath, registry.LockData); err != nil {
 			return nil, err
 		}

internal/topdata/editorconfig_format.go

@@ -203,8 +203,23 @@ func editorConfigPatternMatches(pattern, relativePath string) (bool, error) {
 }
 
 func editorConfigGlobRegexp(pattern string) (string, error) {
+	body, err := translateEditorConfigGlobSegment(pattern)
+	if err != nil {
+		return "", err
+	}
+	expression := "^" + body + "$"
+	if _, err := regexp.Compile(expression); err != nil {
+		return "", err
+	}
+	return expression, nil
+}
+
+// translateEditorConfigGlobSegment converts an editorconfig glob into a regular
+// expression body. In addition to *, **, and ?, it implements brace expansion:
+// comma lists ({a,b,c}) become alternations and numeric ranges ({n..m}) expand
+// to the integers in the range, matching the editorconfig specification.
+func translateEditorConfigGlobSegment(pattern string) (string, error) {
 	var builder strings.Builder
-	builder.WriteByte('^')
 	for index := 0; index < len(pattern); {
 		char := pattern[index]
 		switch char {
@@ -220,22 +235,132 @@ func editorConfigGlobRegexp(pattern string) (string, error) {
 				continue
 			}
 			builder.WriteString("[^/]*")
+			index++
 		case '?':
 			builder.WriteString("[^/]")
-		case '.', '+', '(', ')', '|', '^', '$', '{', '}', '[', ']', '\\':
+			index++
+		case '{':
+			end := matchingEditorConfigBrace(pattern, index)
+			if end < 0 {
+				// An unbalanced brace is matched literally.
+				builder.WriteString("\\{")
+				index++
+				continue
+			}
+			expansion, err := expandEditorConfigBrace(pattern[index+1 : end])
+			if err != nil {
+				return "", err
+			}
+			builder.WriteString(expansion)
+			index = end + 1
+		case '.', '+', '(', ')', '|', '^', '$', '}', '[', ']', '\\':
 			builder.WriteByte('\\')
 			builder.WriteByte(char)
+			index++
 		default:
 			builder.WriteByte(char)
+			index++
 		}
-		index++
 	}
-	builder.WriteByte('$')
+	return builder.String(), nil
-	expression := builder.String()
+}
-	if _, err := regexp.Compile(expression); err != nil {
+
-		return "", err
+// matchingEditorConfigBrace returns the index of the '}' that closes the '{' at
+// open, accounting for nesting, or -1 when the braces are unbalanced.
+func matchingEditorConfigBrace(pattern string, open int) int {
+	depth := 0
+	for index := open; index < len(pattern); index++ {
+		switch pattern[index] {
+		case '{':
+			depth++
+		case '}':
+			depth--
+			if depth == 0 {
+				return index
+			}
+		}
 	}
-	return expression, nil
+	return -1
+}
+
+// expandEditorConfigBrace turns the body of a brace expression into a regex
+// fragment. A comma list becomes an alternation; a lone "n..m" body becomes a
+// numeric range. A body with neither comma nor range is treated as literal
+// braces, matching the editorconfig reference implementation.
+func expandEditorConfigBrace(inner string) (string, error) {
+	options := splitTopLevelBraceCommas(inner)
+	if len(options) == 1 {
+		if rangeExpr, ok, err := editorConfigNumericRange(inner); err != nil {
+			return "", err
+		} else if ok {
+			return rangeExpr, nil
+		}
+		segment, err := translateEditorConfigGlobSegment(inner)
+		if err != nil {
+			return "", err
+		}
+		return "\\{" + segment + "\\}", nil
+	}
+	parts := make([]string, 0, len(options))
+	for _, option := range options {
+		segment, err := translateEditorConfigGlobSegment(option)
+		if err != nil {
+			return "", err
+		}
+		parts = append(parts, segment)
+	}
+	return "(?:" + strings.Join(parts, "|") + ")", nil
+}
+
+// splitTopLevelBraceCommas splits a brace body on commas that are not nested
+// inside an inner brace group.
+func splitTopLevelBraceCommas(inner string) []string {
+	parts := []string{}
+	depth := 0
+	start := 0
+	for index := 0; index < len(inner); index++ {
+		switch inner[index] {
+		case '{':
+			depth++
+		case '}':
+			depth--
+		case ',':
+			if depth == 0 {
+				parts = append(parts, inner[start:index])
+				start = index + 1
+			}
+		}
+	}
+	return append(parts, inner[start:])
+}
+
+// editorConfigNumericRange expands "n..m" into an alternation of the integers
+// in [n, m]. It returns ok=false when the body is not a numeric range.
+func editorConfigNumericRange(inner string) (string, bool, error) {
+	separator := strings.Index(inner, "..")
+	if separator < 0 {
+		return "", false, nil
+	}
+	low, err := strconv.Atoi(strings.TrimSpace(inner[:separator]))
+	if err != nil {
+		return "", false, nil
+	}
+	high, err := strconv.Atoi(strings.TrimSpace(inner[separator+2:]))
+	if err != nil {
+		return "", false, nil
+	}
+	if low > high {
+		low, high = high, low
+	}
+	const maxRangeSize = 65536
+	if high-low >= maxRangeSize {
+		return "", false, fmt.Errorf("editorconfig numeric range {%s} is too large", inner)
+	}
+	parts := make([]string, 0, high-low+1)
+	for value := low; value <= high; value++ {
+		parts = append(parts, strconv.Itoa(value))
+	}
+	return "(?:" + strings.Join(parts, "|") + ")", true, nil
 }
 
 func pathBase(path string) string {

internal/topdata/editorconfig_glob_test.go

@@ -0,0 +1,56 @@
+package topdata
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestEditorConfigPatternMatchesBraceExpansion(t *testing.T) {
+	cases := []struct {
+		pattern string
+		path    string
+		want    bool
+	}{
+		{"*.{json,jsonc}", "lock.json", true},
+		{"*.{json,jsonc}", "types.jsonc", true},
+		{"*.{json,jsonc}", "notes.md", false},
+		{"*.{js,ts,tsx}", "main.tsx", true},
+		{"{foo,bar}.txt", "bar.txt", true},
+		{"{foo,bar}.txt", "baz.txt", false},
+		{"page{1..3}.json", "page2.json", true},
+		{"page{1..3}.json", "page4.json", false},
+		// No comma and not a range: editorconfig treats braces literally.
+		{"{single}.txt", "{single}.txt", true},
+		{"{single}.txt", "single.txt", false},
+	}
+	for _, c := range cases {
+		got, err := editorConfigPatternMatches(c.pattern, c.path)
+		if err != nil {
+			t.Fatalf("pattern %q path %q: %v", c.pattern, c.path, err)
+		}
+		if got != c.want {
+			t.Errorf("editorConfigPatternMatches(%q, %q) = %v, want %v", c.pattern, c.path, got, c.want)
+		}
+	}
+}
+
+func TestSaveLockfileHonorsBraceGlobIndentSize(t *testing.T) {
+	root := t.TempDir()
+	writeFile(t, filepath.Join(root, ".editorconfig"), "root = true\n\n[*]\nindent_style = space\nindent_size = 2\n\n[*.{json,jsonc}]\nindent_size = 4\n")
+	lockPath := filepath.Join(root, "data", "damagetypes", "registry", "lock.json")
+	mkdirAll(t, filepath.Dir(lockPath))
+	writeFile(t, lockPath, "{\n  \"damagetype:acid\": 4\n}\n")
+
+	if err := saveLockfile(lockPath, map[string]int{"damagetype:acid": 4}); err != nil {
+		t.Fatalf("saveLockfile: %v", err)
+	}
+	got, err := os.ReadFile(lockPath)
+	if err != nil {
+		t.Fatalf("read lockfile: %v", err)
+	}
+	want := "{\n    \"damagetype:acid\": 4\n}\n"
+	if string(got) != want {
+		t.Fatalf("expected 4-space indent resolved from [*.{json,jsonc}]; got:\n%q", string(got))
+	}
+}

internal/topdata/itemprops_registry.go

@@ -166,7 +166,7 @@ func loadRegistryRows(path string) ([]map[string]any, error) {
 	return rows, nil
 }
 
-func collectItempropsRegistryDatasets(dataDir string) ([]nativeCollectedDataset, error) {
+func collectItempropsRegistryDatasets(dataDir string, persistLocks bool) ([]nativeCollectedDataset, error) {
 	registry, err := loadItempropsRegistry(dataDir)
 	if err != nil {
 		return nil, err
@@ -188,7 +188,7 @@ func collectItempropsRegistryDatasets(dataDir string) ([]nativeCollectedDataset,
 		return nil, err
 	}
 	lockModified = lockModified || costModified || paramModified
-	if lockModified {
+	if lockModified && persistLocks {
 		if err := saveLockfile(registry.LockPath, registry.LockData); err != nil {
 			return nil, err
 		}

internal/topdata/native.go

@@ -398,7 +398,7 @@ func buildNativeUnchecked(p *project.Project, opts NativeBuildOptions, progress
 	datasets = applyTopDataValueEncodings(datasets, p.Config.TopData.ValueEncodings)
 	datasets = applyTopDataValueDefaults(datasets, p.Config.TopData.ValueDefaults)
 	datasets = applyTopDataRowGeneration(datasets, p.Config.TopData.RowGeneration)
-	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir)
+	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir, true)
 	if err != nil {
 		return BuildResult{}, err
 	}
@@ -1073,7 +1073,7 @@ func discoverNativeOutputCatalog(dataDir string) (map[string]string, error) {
 	if err != nil {
 		return nil, err
 	}
-	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir)
+	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir, false)
 	if err != nil {
 		return nil, err
 	}

internal/topdata/racialtypes_registry.go

@@ -120,7 +120,7 @@ func loadRacialtypesRegistryRaceRows(dir string) ([]map[string]any, error) {
 	return rows, nil
 }
 
-func collectRacialtypesRegistryDatasets(dataDir string) ([]nativeCollectedDataset, error) {
+func collectRacialtypesRegistryDatasets(dataDir string, persistLocks bool) ([]nativeCollectedDataset, error) {
 	registry, err := loadRacialtypesRegistry(dataDir)
 	if err != nil {
 		return nil, err
@@ -138,7 +138,7 @@ func collectRacialtypesRegistryDatasets(dataDir string) ([]nativeCollectedDatase
 		return nil, err
 	}
 	lockModified = lockModified || raceLockModified
-	if lockModified {
+	if lockModified && persistLocks {
 		if err := saveLockfile(registry.LockPath, registry.LockData); err != nil {
 			return nil, err
 		}

internal/topdata/registry_readonly_test.go

@@ -0,0 +1,64 @@
+package topdata
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+const damagetypesRegistryTestTypes = `{
+  "rows": [
+    {"id": 0, "key": "damagetype:bludgeoning", "label": "Bludgeoning", "group_label": "Physical", "damage_type_group": 0},
+    {"id": 1, "key": "damagetype:piercing", "label": "Piercing", "group_label": "Physical", "damage_type_group": 0}
+  ]
+}
+`
+
+// validate-topdata must never modify source lockfiles. Collection in read-only
+// mode must leave the registry lock byte-identical even though the rows carry
+// explicit ids that would otherwise mark the lock "modified".
+func TestCollectGeneratedRegistryDatasetsReadOnlyDoesNotWriteLock(t *testing.T) {
+	dataDir := t.TempDir()
+	regDir := filepath.Join(dataDir, "damagetypes", "registry")
+	mkdirAll(t, regDir)
+	writeFile(t, filepath.Join(regDir, "types.json"), damagetypesRegistryTestTypes)
+
+	lockPath := filepath.Join(regDir, "lock.json")
+	original := "{\n    \"damagetype:bludgeoning\": 0,\n    \"damagetype:piercing\": 1\n}\n"
+	writeFile(t, lockPath, original)
+
+	if _, err := collectGeneratedRegistryDatasets(dataDir, false); err != nil {
+		t.Fatalf("read-only collection failed: %v", err)
+	}
+
+	got, err := os.ReadFile(lockPath)
+	if err != nil {
+		t.Fatalf("read lockfile: %v", err)
+	}
+	if string(got) != original {
+		t.Fatalf("read-only collection must not modify lockfile.\nwant: %q\ngot:  %q", original, string(got))
+	}
+}
+
+// build-topdata still persists allocated ids to source lockfiles.
+func TestCollectGeneratedRegistryDatasetsPersistWritesLock(t *testing.T) {
+	dataDir := t.TempDir()
+	regDir := filepath.Join(dataDir, "damagetypes", "registry")
+	mkdirAll(t, regDir)
+	writeFile(t, filepath.Join(regDir, "types.json"), damagetypesRegistryTestTypes)
+
+	lockPath := filepath.Join(regDir, "lock.json")
+	writeFile(t, lockPath, "{\n    \"damagetype:bludgeoning\": 0\n}\n")
+
+	if _, err := collectGeneratedRegistryDatasets(dataDir, true); err != nil {
+		t.Fatalf("persisting collection failed: %v", err)
+	}
+
+	lockData, err := loadLockfile(lockPath)
+	if err != nil {
+		t.Fatalf("load lockfile: %v", err)
+	}
+	if lockData["damagetype:piercing"] != 1 {
+		t.Fatalf("persisting collection should record allocated id; got %#v", lockData)
+	}
+}

internal/topdata/top_package.go

@@ -557,7 +557,7 @@ func expectedCompiled2DAOutputs(p *project.Project) (map[string]struct{}, error)
 	if err != nil {
 		return nil, err
 	}
-	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir)
+	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir, false)
 	if err != nil {
 		return nil, err
 	}

internal/topdata/topdata.go

@@ -1320,7 +1320,7 @@ func validateNativeOutputCatalog(dataDir string, report *ValidationReport) {
 		})
 		return
 	}
-	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir)
+	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir, false)
 	if err != nil {
 		report.Diagnostics = append(report.Diagnostics, Diagnostic{
 			Severity: SeverityError,
@@ -2307,7 +2307,7 @@ func validateNativeBuildability(p *project.Project, report *ValidationReport) {
 		})
 		return
 	}
-	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir)
+	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir, false)
 	if err != nil {
 		report.Diagnostics = append(report.Diagnostics, Diagnostic{
 			Severity: SeverityError,

internal/topdata/wiki_native.go

@@ -748,7 +748,7 @@ func collectWikiRacialtypesDatasets(dataDir string, datasets []nativeDataset) ([
 	if len(out) > 0 {
 		return out, nil
 	}
-	return collectRacialtypesRegistryDatasets(dataDir)
+	return collectRacialtypesRegistryDatasets(dataDir, false)
 }
 
 func collectWikiRacialtypeStatuses(dataDir string) map[string]string {

wrappers/consumers.txt

@@ -0,0 +1,5 @@
+# Repos that carry copies of the canonical Crucible wrappers.
+# One "owner/repo" per line. sync-wrappers.yml opens an update PR to each when
+# wrappers/ changes. Add a repo here AND grant the sync bot write access to it.
+ShadowsOverWestgate/sow-module
+ShadowsOverWestgate/sow-topdata