docs: describe how a contested slot is decided

tests/test_doc_pages.py

@@ -1720,6 +1720,27 @@ class ReadmeKeepsItsPointers(unittest.TestCase):
         self.assertRegex(readme, r"more the collection does not hold and does not serve by name")
 
 
+class ArchitectureStatesTheArbitration(unittest.TestCase):
+    """architecture.md said the profile takes precedence for pack generation,
+    while slots.arbitrate() keeps the platform's file where its frontend
+    checks the content: RetroBat's ATARIOSB.ROM."""
+
+    def test_the_page_says_what_arbitrate_decides(self):
+        import slots  # noqa: PLC0415
+
+        page = (WIKI / "architecture.md").read_text(encoding="utf-8")
+        self.assertNotIn("the profile takes precedence for pack generation", page)
+        section = page[page.index("### When both layers claim one destination"):]
+        section = section[:section.index("\n## ")]
+        self.assertIn("`slots.arbitrate()`", section)
+        source = inspect.getsource(slots.arbitrate)
+        # The three outcomes the section describes.
+        for outcome in ("ADDRESSEE", "SERVES_BOTH", "FRONTEND_CHECKS_CONTENT"):
+            self.assertIn(outcome, source)
+        for said in ("--emulator", "`existence`", "the platform's file stays"):
+            self.assertIn(said, section)
+
+
 class ReportExcerptIsTheRun(unittest.TestCase):
     """reading-reports.md quoted 'From python scripts/verify.py --platform
     retrodeck' a run that said 0 required missing after the command had started

wiki/architecture.md

@@ -169,11 +169,31 @@ The emulator's source code serves as ground truth for what files are needed,
 what names they use, and what validation the emulator performs. Platform YAML
 configs are scraped from upstream and record what each platform declares. A
 list kept by hand can lag behind an emulator release. The emulator profiles complement the
-platform data by documenting what the code actually loads. When the two disagree,
-the profile takes precedence for pack generation: files the code needs are included
-even if the platform does not declare them. Files the platform declares but no
-profile references are kept as well (flagged during cross-reference), since the
-upstream may cover cases not yet profiled.
+platform data by documenting what the code actually loads. Files the code needs
+are included even if the platform does not declare them. Files the platform
+declares but no profile references are kept as well (flagged during
+cross-reference), since the upstream may cover cases not yet profiled.
+
+### When both layers claim one destination
+
+A platform and an emulator profile can each name a different file for the same
+place in the BIOS folder: RetroBat puts its own `ATARIOSB.ROM` at
+`bios/ATARIOSB.ROM`, where atari800 reads another dump. A claim counts only when
+it rests on content or on the path. A file found by its name alone claims
+nothing. The pack then answers to whoever asked for it:
+
+- A **platform pack** must leave the frontend's own check green, since a user
+  reading red concludes the pack is broken. Where the frontend only looks for
+  the name (`existence`), the emulator's file satisfies both, and the pack takes
+  it. Where the frontend checks an MD5 or SHA1, one path cannot hold both
+  answers: the platform's file stays, and the loss is reported. Only the
+  platform's own list can change what its frontend accepts there.
+- A pack built with `--emulator` answers to that emulator, and takes its file.
+
+`scripts/slots.py` prints each contested destination and the reason for its
+winner (`python scripts/slots.py --platform retrobat`). `generate_pack.py` and
+`verify.py` both decide through `slots.arbitrate()`, so the pack and the report
+agree.
 
 A platform YAML is regenerated by its scraper and never edited by hand: an
 edit would be lost at the next scrape, and the file would stop describing the