feat(nwsync): emit blobs and per-artifact NSYM, assemble merged manifests (#71)

Builds sow-tools#53. Format spec followed is the resolution comment of sow-platform#94, checked line by line against niv/neverwinter.nim at HEAD (`nwsync.nim`, `compressedbuf.nim`, `nwsync/private/libupdate.nim`).

## What lands

`crucible nwsync emit <artifact> --out DIR` — explodes one `.hak`/`.erf`, or one loose file such as the TLK, into NWSync blobs plus a NSYM v3 manifest covering only that artifact, with the same `.json` sidecar upstream writes. Blob path `data/sha1/<h0h1>/<h2h3>/<sha1>`, body in NWCompressedBuffer framing (magic `NSYC`, version 3, algorithm 2, uncompressed size, zstd header version 1, dictionary 0, raw zstd frame). The sha1 that names a blob is over the uncompressed bytes.

`crucible nwsync assemble --order NAMES --entries DIR --out DIR [--group-id N]` — merges the per-artifact manifests into one, reading no bulk data at all. Merge rule is resref shadowing, not concatenation: a resref in more than one artifact resolves to the earliest artifact in `--order`, which is how the game resolves it. `--group-id` stays caller-supplied (1 current, 2 testing; 0 is absent, matching upstream omitting a zero integer meta field).

Rules taken from upstream and not re-invented: `nss`/`ndb`/`gic` always skipped; an unresolvable restype is a hard error, not a skip; a resource over 15 MB fails closed; no `latest` file and no `.origin` file, ever. A `.mod` is refused outright — a persistent world publishes no module contents, so the module contributes no bytes.

## Two deliberate departures

- **Emitter version is its own field, not the build revision.** `emitter_version` is a constant bumped only when emitted bytes change. Keying the refuse-to-merge check on `created_with` would invalidate every published index on every unrelated crucible commit and force a re-emit of the whole 15 GB corpus — the opposite of "nothing downstream ever needs the hak again".
- **`SOURCE_DATE_EPOCH` pins the sidecar timestamp.** The manifest itself was already deterministic; the sidecar's `created` was not, against the determinism rule in `docs/consumer-contract.md`.

## Not in this PR, and why

- **Direct upload.** Only the local `--out` sink exists, which is the conformance path. The upload sink and the mid-hak-failure question are sow-tools#60, and the consumer wiring is #65.
- **The conformance run against upstream.** sow-tools#59 owns getting `nwn_nwsync_write` running and capturing reference output. The format here was read from upstream source rather than from its output, so the byte-for-byte manifest comparison and the after-decompression blob comparison still have to happen — that is what #59 is for. The tests in this PR check the layout against the spec, so a shared misreading would pass them.
- **The `artifacts/haks/sha256/<a>/<b>/<sha256>.nsym` location.** emit writes `<out>/<name>.nsym`; where a publisher puts it is the publisher's business (#65).
- **The acceptance gate** — a real client syncing from an assembled manifest — is unchanged and still open.

## Checks

`make check` green (vet, unit tests, shellcheck, yamllint, workflow contract), `make smoke` green with the new builder, `nix build .#crucible` produces `crucible-nwsync`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: #71

Co-authored-by: vickydotbat <vickydotbat@tutamail.com>

internal/nwsync/assemble.go

@@ -0,0 +1,111 @@
+package nwsync
+
+import (
+	"crypto/sha1"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+// AssembleOptions describes one merged manifest.
+type AssembleOptions struct {
+	Order       []string // artifact names, highest priority first
+	EntriesDir  string   // directory holding <name>.nsym and <name>.nsym.json
+	OutDir      string   // repository root; the manifest lands in <out>/manifests
+	GroupID     int      // 1 = current, 2 = testing; 0 means absent
+	ModuleName  string
+	Description string
+}
+
+// AssembleResult reports what one assemble run produced.
+type AssembleResult struct {
+	SHA1         string
+	ManifestPath string
+	Entries      int
+}
+
+// Assemble merges the per-artifact NSYM manifests named by Order into one
+// manifest. It reads no bulk data at all — only the small index files.
+//
+// Merge rule is resref shadowing, not concatenation: a resref present in more
+// than one artifact resolves to the earliest artifact in Order, which is how
+// the game resolves it (upstream's resman adds haks in reverse and lets the
+// last one win). Get this backwards and the wrong texture ships silently.
+func Assemble(options AssembleOptions) (AssembleResult, error) {
+	if len(options.Order) == 0 {
+		return AssembleResult{}, fmt.Errorf("assemble: --order names no artifacts")
+	}
+
+	merged := make([]Entry, 0, 1024)
+	winner := make(map[Identity]bool, 1024)
+	var onDiskBytes int64
+
+	for _, name := range options.Order {
+		manifestPath := filepath.Join(options.EntriesDir, name+".nsym")
+		data, err := os.ReadFile(manifestPath)
+		if err != nil {
+			return AssembleResult{}, fmt.Errorf("assemble: no index for %q: %w", name, err)
+		}
+		entries, err := readManifest(data)
+		if err != nil {
+			return AssembleResult{}, fmt.Errorf("%s: %w", manifestPath, err)
+		}
+		sidecar, err := readSidecar(manifestPath + ".json")
+		if err != nil {
+			return AssembleResult{}, err
+		}
+		// Two producers of blobs means a skewed emitter can write blobs the
+		// merged manifest quietly disagrees with. Refuse to merge across
+		// mismatched emitter versions.
+		if sidecar.EmitterVersion != emitterVersion {
+			return AssembleResult{}, fmt.Errorf(
+				"assemble: emitter version mismatch: %s was emitted by emitter %q, this is emitter %q",
+				name, sidecar.EmitterVersion, emitterVersion)
+		}
+		// on_disk_bytes overcounts by the handful of cross-artifact
+		// duplicates. It is a display statistic; no dedupe pass for it.
+		onDiskBytes += sidecar.OnDiskBytes
+
+		for _, entry := range entries {
+			identity := entry.identity()
+			if winner[identity] {
+				continue
+			}
+			winner[identity] = true
+			merged = append(merged, entry)
+		}
+	}
+
+	if len(merged) == 0 {
+		return AssembleResult{}, fmt.Errorf("assemble: merged manifest is empty")
+	}
+
+	data, err := writeManifest(merged)
+	if err != nil {
+		return AssembleResult{}, err
+	}
+	sha1Hex := fmt.Sprintf("%x", sha1.Sum(data))
+	manifestPath := filepath.Join(options.OutDir, "manifests", sha1Hex)
+	sidecar := Sidecar{
+		ModuleName:  options.ModuleName,
+		Description: options.Description,
+		GroupID:     options.GroupID,
+	}
+	if err := writeManifestPair(manifestPath, data, merged, onDiskBytes, sidecar); err != nil {
+		return AssembleResult{}, err
+	}
+	return AssembleResult{SHA1: sha1Hex, ManifestPath: manifestPath, Entries: len(merged)}, nil
+}
+
+func readSidecar(path string) (Sidecar, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return Sidecar{}, fmt.Errorf("assemble: missing sidecar: %w", err)
+	}
+	var sidecar Sidecar
+	if err := json.Unmarshal(data, &sidecar); err != nil {
+		return Sidecar{}, fmt.Errorf("%s: %w", path, err)
+	}
+	return sidecar, nil
+}