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/run.go

@@ -0,0 +1,129 @@
+// Package nwsync publishes NWSync repository data: blobs and a per-artifact
+// NSYM manifest at each artifact's birth (emit), and one merged manifest at
+// module release (assemble).
+//
+// The split exists because upstream nwn_nwsync_write wants every hak, the TLK
+// and the module present in one run on one disk, which our build hosts cannot
+// hold. Upstream stays the conformance oracle: manifests compare byte for
+// byte, blobs compare after decompression.
+package nwsync
+
+import (
+	"flag"
+	"fmt"
+	"io"
+	"strings"
+)
+
+const (
+	exitOK       = 0
+	exitUsage    = 64
+	exitInternal = 70
+)
+
+// Run executes an nwsync subcommand. args[0] is the subcommand (emit|assemble);
+// returns the process exit code.
+func Run(args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 {
+		printRunUsage(stderr)
+		return exitUsage
+	}
+	switch args[0] {
+	case "emit":
+		return runEmit(args[1:], stdout, stderr)
+	case "assemble":
+		return runAssemble(args[1:], stdout, stderr)
+	case "-h", "--help", "help":
+		printRunUsage(stdout)
+		return exitOK
+	default:
+		fmt.Fprintf(stderr, "nwsync: unknown subcommand %q\n\n", args[0])
+		printRunUsage(stderr)
+		return exitUsage
+	}
+}
+
+func printRunUsage(w io.Writer) {
+	fmt.Fprint(w, `usage:
+  nwsync emit     <artifact> --out DIR
+  nwsync assemble --order NAMES --entries DIR --out DIR [--group-id N]
+
+emit explodes one .hak/.erf or one loose file (the TLK) into NWSync blobs plus
+a NSYM manifest covering only that artifact. assemble merges those per-artifact
+manifests into one, reading no bulk data.
+`)
+}
+
+func runEmit(args []string, stdout, stderr io.Writer) int {
+	fs := flag.NewFlagSet("emit", flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	out := fs.String("out", "", "output directory (blobs plus the per-artifact manifest)")
+	if err := fs.Parse(args); err != nil {
+		return exitUsage
+	}
+	if fs.NArg() != 1 {
+		fmt.Fprintf(stderr, "nwsync emit: exactly one artifact is required\n")
+		return exitUsage
+	}
+	if *out == "" {
+		fmt.Fprintf(stderr, "nwsync emit: --out is required\n")
+		return exitUsage
+	}
+
+	result, err := Emit(fs.Arg(0), *out)
+	if err != nil {
+		fmt.Fprintf(stderr, "nwsync emit: %v\n", err)
+		return exitInternal
+	}
+	fmt.Fprintf(stdout, "emitted %s: %d resources, %d new blobs, manifest %s\n",
+		result.Name, result.Entries, result.BlobsWritten, result.ManifestPath)
+	return exitOK
+}
+
+func runAssemble(args []string, stdout, stderr io.Writer) int {
+	fs := flag.NewFlagSet("assemble", flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	order := fs.String("order", "", "comma-separated artifact names, highest priority first")
+	entries := fs.String("entries", "", "directory holding the per-artifact .nsym files")
+	out := fs.String("out", "", "repository root; the manifest lands in <out>/manifests")
+	groupID := fs.Int("group-id", 0, "NWSync group id (1 = current, 2 = testing; 0 omits it)")
+	moduleName := fs.String("module-name", "", "module name recorded in the sidecar")
+	description := fs.String("description", "", "description recorded in the sidecar")
+	if err := fs.Parse(args); err != nil {
+		return exitUsage
+	}
+	switch {
+	case *order == "":
+		fmt.Fprintf(stderr, "nwsync assemble: --order is required\n")
+		return exitUsage
+	case *entries == "":
+		fmt.Fprintf(stderr, "nwsync assemble: --entries is required\n")
+		return exitUsage
+	case *out == "":
+		fmt.Fprintf(stderr, "nwsync assemble: --out is required\n")
+		return exitUsage
+	}
+
+	names := make([]string, 0, 8)
+	for _, name := range strings.Split(*order, ",") {
+		if name = strings.TrimSpace(name); name != "" {
+			names = append(names, name)
+		}
+	}
+
+	result, err := Assemble(AssembleOptions{
+		Order:       names,
+		EntriesDir:  *entries,
+		OutDir:      *out,
+		GroupID:     *groupID,
+		ModuleName:  *moduleName,
+		Description: *description,
+	})
+	if err != nil {
+		fmt.Fprintf(stderr, "nwsync assemble: %v\n", err)
+		return exitInternal
+	}
+	fmt.Fprintf(stdout, "assembled %s: %d resources from %d artifacts\n",
+		result.SHA1, result.Entries, len(names))
+	return exitOK
+}