chore: merge audit fixes (docs)

# Conflicts:
#	tests/test_doc_surfaces.py
#	wiki/installer.md
#	wiki/testing-guide.md

scripts/generate_pack.py

@@ -1252,16 +1252,10 @@ class DamagedArchiveError(OSError):
 def _normalize_zip_for_pack(
     source_zip: str, dest_path: str, target_zf: zipfile.ZipFile
 ) -> None:
-    """Add a MAME BIOS ZIP to the pack as a deterministic rebuild.
+    """Add a MAME BIOS ZIP to the pack, rebuilt from its ROMs.
 
-    Instead of copying the original ZIP (with non-deterministic metadata),
-    extracts the ROM atoms, rebuilds the ZIP deterministically, and writes
-    the normalized version into the pack.
-
-    This ensures:
-    - Same ROMs -> same ZIP hash in every pack build
-    - No dependency on how the user built their MAME ROM set
-    - Bit-identical ZIPs across platforms and build times
+    The same ROMs give the same archive bytes in every build, whatever
+    metadata the source ZIP carried.
     """
     import tempfile as _tmp
 

scripts/generate_readme.py

@@ -380,7 +380,7 @@ def generate_readme(db: dict, platforms_dir: str) -> str:
         "A pack holds the files its emulators read, as their source code names"
         " them, and leaves out what the emulators install themselves.",
         "",
-        "## Quick Install",
+        "## Quick install",
         "",
         "Copy one command into your terminal:",
         "",
@@ -404,12 +404,6 @@ def generate_readme(db: dict, platforms_dir: str) -> str:
         "## Download BIOS packs",
         "",
         "One pack per platform, and it holds everything the platform runs: its own BIOS list plus every file its emulator cores load. Pick your platform, download the ZIP, extract to the BIOS path. The installer above does the same file by file. At a terminal it asks whether to install everything or to choose systems, cores and regions, and `--system`, `--core`, `--region` and `--target` make the same choice without questions. For a bare minimum, build your own pack below.",
-        "Files is how many the pack holds once extracted, the figure a file"
-        " manager shows for the folder. It differs from one platform to the"
-        " next because a pack carries only what that platform's emulators"
-        " load."
-        " The size is what the files occupy once extracted, and the ZIP itself"
-        " downloads smaller.",
         "",
         "A pack over 2 GB comes in several parts (`Pack.part1of2.zip`,"
         " `Pack.part2of2.zip`), and every part is needed. Each part is an"
@@ -421,6 +415,12 @@ def generate_readme(db: dict, platforms_dir: str) -> str:
         "(https://abdess.github.io/retrobios/wiki/release-process/"
         "#verifying-a-release).",
         "",
+        "The Files column counts what a pack holds once extracted, the figure a"
+        " file manager shows for the folder. It differs from one platform to"
+        " the next because a pack carries only what that platform's emulators"
+        " load. The size is what the files occupy once extracted, and the ZIP"
+        " itself downloads smaller.",
+        "",
     ]
 
     # Where the pack itself is extracted, which is not always the BIOS folder:

scripts/truth.py

@@ -39,27 +39,13 @@ def _serialize_source_ref(sr: object) -> str:
 
 
 def _enrich_hashes(entry: dict, db: dict) -> None:
-    """Fill missing sibling hashes from the database, ground-truth preserving.
+    """Fill the hashes a profile omits from the record its own hash names.
 
-    The profile's hashes come from the emulator source code (ground truth).
-    Any hash of a given file set of bytes is a projection of that same
-    ground truth. sha1, md5 and crc32 all identify the same bytes. If the
-    profile has ONE ground-truth hash, the DB can supply its siblings.
-
-    Lookup order (all are hash-anchored, never name-based):
-      1. SHA1 direct
-      2. MD5 -> SHA1 via indexes.by_md5
-      3. CRC32 -> SHA1 via indexes.by_crc32 (weaker 32-bit anchor,
-         requires size match when profile has size)
-
-    Name-based enrichment is NEVER used: a name alone has no ground-truth
-    anchor, the file in bios/ may not match what the source code expects.
-
-    Multi-hash entries (lists of accepted variants) are left untouched to
-    preserve variant information.
+    The record is found by sha1, then md5, then crc32 with the size when the
+    profile gives one. Never by name: a file in bios/ under the same name may
+    not be the bytes the source code expects. An entry listing several
+    accepted values for a hash is left as is.
     """
-    # Skip multi-hash entries. They express ground truth as "any of these N
-    # variants", enriching with a single sibling would lose that information.
     for h in ("sha1", "md5", "crc32"):
         if isinstance(entry.get(h), list):
             return
@@ -105,7 +91,6 @@ def _enrich_hashes(entry: dict, db: dict) -> None:
         return
 
     # Copy sibling hashes and size from the anchored record.
-    # These are projections of the same ground-truth bytes.
     for field in ("sha1", "md5", "sha256", "crc32"):
         if not entry.get(field) and record.get(field):
             entry[field] = record[field]