fix(engine): make .seed_version marker authoritative (no boot refusal)

The seed-drift guard shipped as refuse-boot: the backend exited when
BACKEND_DICT_VERSION disagreed with the flat dir's recorded .seed_version. On
the test contour that turned a harmless-in-intent action — bumping the
TEST_DICT_VERSION variable to the active release (v1.2.1) on a volume seeded as
v1.0.0 — into a crash loop, because DICT_VERSION is the *seed* of a fresh
volume, not the active version (which the admin console drives).

Make the marker authoritative instead: OpenWithVersions resolves the flat dir's
version from .seed_version when present and ignores bootVersion on an
already-seeded volume; bootVersion only seeds a fresh volume's marker. So a
bumped build seed on a live volume is a no-op (it can't relabel live bytes and
can't void games pinned to the prior label), and it correctly seeds the next
fresh volume. The subdirectory scan now skips the resolved seed, so a version
also present as a subdir (e.g. v1.2.1 uploaded via the console while the build
seed is bumped to v1.2.1) is still loaded rather than shadowed by the flat bytes.

Tests: marker-wins over a bumped boot version; a bumped boot keeps the matching
subdir resident (the live-contour case). Docs updated (ARCHITECTURE §5, READMEs,
compose/.env, PRERELEASE DV) from "refuses to boot" to "marker wins / ignored".

Verified locally against v1.2.1: gofmt, build, vet, unit, integration green.

backend/internal/engine/registry.go

@@ -70,20 +70,22 @@ func Open(dir, version string, variants ...Variant) (*Registry, error) {
 // immediate subdirectory of dir: a subdirectory named V contributes, under
 // version V, the variants whose committed DAWG it carries. This is the
 // restart-side of the admin dictionary reload — a version reloaded into dir/<V>/
-// at runtime is resident again after a restart. A subdirectory named like the
-// boot version is skipped (the flat dir already is the boot version). It records
-// and enforces a seed-version marker on the flat dir (see checkSeedMarker), failing
-// when the build seed was bumped on an already-seeded volume. A partially loaded
+// at runtime is resident again after a restart. The flat dir's version is resolved
+// from its .seed_version marker (see resolveSeedVersion): a fresh dir records
+// bootVersion, an already-seeded dir keeps its recorded label and ignores bootVersion,
+// so a bumped build seed never relabels live bytes. A subdirectory named like the
+// resolved seed version is skipped (the flat dir already is it). A partially loaded
 // registry is closed before any error is returned.
 func OpenWithVersions(dir, bootVersion string) (*Registry, error) {
-	r, err := Open(dir, bootVersion)
+	// Resolve the flat dir's version from its seed marker first: on an already-seeded
+	// volume the marker wins and bootVersion is ignored, so a bumped build seed cannot
+	// relabel live bytes (see resolveSeedVersion).
+	seed, err := resolveSeedVersion(dir, bootVersion)
 	if err != nil {
 		return nil, err
 	}
-	// Guard the seed-drift footgun before scanning for additional versions: refuse
-	// to boot when the flat dir was seeded under a different version than bootVersion.
-	if err := checkSeedMarker(dir, bootVersion); err != nil {
-		_ = r.Close()
+	r, err := Open(dir, seed)
+	if err != nil {
 		return nil, err
 	}
 	entries, err := os.ReadDir(dir)
@@ -92,9 +94,9 @@ func OpenWithVersions(dir, bootVersion string) (*Registry, error) {
 		return nil, fmt.Errorf("engine: scan dictionary dir %s: %w", dir, err)
 	}
 	for _, e := range entries {
-		// Skip non-directories, the boot version (already loaded as the flat dir)
-		// and dot-prefixed directories (the upload staging area, dir/.staging/).
-		if !e.IsDir() || e.Name() == bootVersion || strings.HasPrefix(e.Name(), ".") {
+		// Skip non-directories, the resolved seed version (already loaded as the flat
+		// dir) and dot-prefixed directories (the upload staging area, dir/.staging/).
+		if !e.IsDir() || e.Name() == seed || strings.HasPrefix(e.Name(), ".") {
 			continue
 		}
 		if _, err := r.LoadAvailable(filepath.Join(dir, e.Name()), e.Name()); err != nil {

backend/internal/engine/reload_test.go

@@ -146,23 +146,67 @@ func TestOpenWithVersionsRecordsSeedMarker(t *testing.T) {
 	_ = reg2.Close()
 }
 
-// TestOpenWithVersionsRejectsSeedDrift verifies the guard refuses to boot a directory
-// seeded as one version when BACKEND_DICT_VERSION (bootVersion) names another — the
-// seed-drift footgun a bumped build seed on a live volume would cause.
-func TestOpenWithVersionsRejectsSeedDrift(t *testing.T) {
+// TestOpenWithVersionsMarkerWinsOverBoot verifies the recorded .seed_version marker
+// is authoritative: once a directory is seeded, a different bootVersion
+// (BACKEND_DICT_VERSION) is ignored — the flat dir keeps its recorded label — so a
+// bumped build seed on a live volume cannot relabel the already-seeded bytes.
+func TestOpenWithVersionsMarkerWinsOverBoot(t *testing.T) {
 	dir := t.TempDir()
 	for _, v := range Variants() {
 		copyDawg(t, testDictDir(), dir, v)
 	}
 
-	reg, err := OpenWithVersions(dir, "v1")
+	reg, err := OpenWithVersions(dir, "v1") // seeds the marker = v1
 	if err != nil {
 		t.Fatalf("seed open: %v", err)
 	}
 	_ = reg.Close()
 
-	if _, err := OpenWithVersions(dir, "v2"); err == nil {
-		t.Fatal("open after seed bump: want error, got nil")
+	// Reboot with a bumped boot version: the marker (v1) wins, no error, v2 ignored.
+	reg2, err := OpenWithVersions(dir, "v2")
+	if err != nil {
+		t.Fatalf("reboot with bumped boot version: %v", err)
+	}
+	defer func() { _ = reg2.Close() }()
+	if got := reg2.Versions(VariantEnglish); len(got) != 1 || got[0] != "v1" {
+		t.Errorf("versions = %v, want [v1] (marker wins, v2 ignored)", got)
+	}
+	if _, err := reg2.Solver(VariantEnglish, "v2"); !errors.Is(err, ErrUnknownVersion) {
+		t.Errorf("v2 must not be resident: got %v", err)
+	}
+	data, _ := os.ReadFile(filepath.Join(dir, seedMarkerFile))
+	if got := strings.TrimSpace(string(data)); got != "v1" {
+		t.Errorf("marker = %q, want v1 (unchanged)", got)
+	}
+}
+
+// TestOpenWithVersionsBumpedBootKeepsSubdir mirrors the live-contour case: a volume
+// seeded as v1 with a v2 subdirectory (uploaded via the console), booted with a bumped
+// build seed bootVersion=v2. The marker (v1) wins for the flat dir, and the v2
+// subdirectory is still loaded — not skipped as "the boot version" — so both versions
+// stay resident. (Skipping it would silently leave only the flat v1 bytes under v2.)
+func TestOpenWithVersionsBumpedBootKeepsSubdir(t *testing.T) {
+	dir := t.TempDir()
+	for _, v := range Variants() {
+		copyDawg(t, testDictDir(), dir, v)
+	}
+	reg0, err := OpenWithVersions(dir, "v1") // seed marker = v1
+	if err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+	_ = reg0.Close()
+	copyDawg(t, testDictDir(), filepath.Join(dir, "v2"), VariantEnglish) // console upload
+
+	reg, err := OpenWithVersions(dir, "v2") // bumped build seed
+	if err != nil {
+		t.Fatalf("boot v2: %v", err)
+	}
+	defer func() { _ = reg.Close() }()
+	if _, err := reg.Solver(VariantEnglish, "v1"); err != nil {
+		t.Errorf("flat v1 must stay resident: %v", err)
+	}
+	if _, err := reg.Solver(VariantEnglish, "v2"); err != nil {
+		t.Errorf("v2 subdir must be resident (not skipped): %v", err)
 	}
 }
 

backend/internal/engine/seedmarker.go

@@ -13,40 +13,41 @@ import (
 // version scan skips it (like the .staging upload area).
 const seedMarkerFile = ".seed_version"
 
-// checkSeedMarker reconciles the flat dictionary directory's recorded seed version
-// with bootVersion, guarding the seed-drift footgun.
+// resolveSeedVersion returns the version label the flat dictionary directory is
+// addressed by, recording it on first use.
 //
 // The contour's dictionary lives on a named volume seeded from the image once and
-// never re-seeded (deploy/docker-compose.yml). The flat directory's DAWG files carry
-// no embedded version, so their version is only the label BACKEND_DICT_VERSION gives
-// them. Bumping the build seed on a live volume would therefore relabel the already
-// seeded bytes: games that pinned the old label become unreplayable (voided) and new
-// games would silently use the wrong dictionary. checkSeedMarker records the seed
-// version on a fresh directory and, on every later boot, returns an error when
-// bootVersion no longer matches the recorded seed — so an operator changes a live
-// dictionary by uploading the new release through the admin console, or wipes the
-// volume to re-seed, never by bumping the build seed (docs/ARCHITECTURE.md §5).
+// never re-seeded (deploy/docker-compose.yml). The flat DAWGs carry no embedded
+// version, so the version a volume was first seeded as is recorded in a
+// .seed_version marker and is **authoritative** from then on:
 //
-// A directory that cannot be written makes the first record fail; that already breaks
+//   - fresh directory (no marker): record bootVersion (the build's
+//     BACKEND_DICT_VERSION) and return it — the seed of a fresh volume;
+//   - already-seeded directory: return the recorded marker and ignore bootVersion.
+//
+// So bumping the build seed on a live volume is a harmless no-op (it only takes
+// effect on a future fresh volume) instead of relabelling the already-seeded bytes —
+// which would void games pinned to the prior label and mis-serve new ones. New games
+// still pin the active version (DB-persisted, set by the admin console), which is the
+// real way a running contour moves to a new release.
+//
+// A directory that cannot be written makes the first record fail; that also breaks
 // the admin console (which writes version subdirectories here), so the error is
 // returned rather than swallowed, matching the package's fail-loud dictionary setup.
-func checkSeedMarker(dir, bootVersion string) error {
+func resolveSeedVersion(dir, bootVersion string) (string, error) {
 	path := filepath.Join(dir, seedMarkerFile)
 	data, err := os.ReadFile(path)
-	switch {
-	case err == nil:
-		if recorded := strings.TrimSpace(string(data)); recorded != bootVersion {
-			return fmt.Errorf("engine: dictionary volume was seeded as %q but BACKEND_DICT_VERSION is %q; "+
-				"change a live dictionary by uploading the release through the admin console, or wipe the "+
-				"volume to re-seed — do not bump the build seed (docs/ARCHITECTURE.md §5)", recorded, bootVersion)
-		}
-		return nil
-	case errors.Is(err, os.ErrNotExist):
-		if err := os.WriteFile(path, []byte(bootVersion+"\n"), 0o644); err != nil {
-			return fmt.Errorf("engine: record dictionary seed marker %s: %w", path, err)
-		}
-		return nil
-	default:
-		return fmt.Errorf("engine: read dictionary seed marker %s: %w", path, err)
+	if err != nil && !errors.Is(err, os.ErrNotExist) {
+		return "", fmt.Errorf("engine: read dictionary seed marker %s: %w", path, err)
 	}
+	if err == nil {
+		if recorded := strings.TrimSpace(string(data)); recorded != "" {
+			return recorded, nil
+		}
+		// An empty/corrupt marker falls through and is rewritten from bootVersion.
+	}
+	if werr := os.WriteFile(path, []byte(bootVersion+"\n"), 0o644); werr != nil {
+		return "", fmt.Errorf("engine: record dictionary seed marker %s: %w", path, werr)
+	}
+	return bootVersion, nil
 }