From 71457078e69fd2675cdcf446b2bee172ff67039e Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Thu, 5 Nov 2026 19:55:39 +0100
Subject: [PATCH] docs: state the cross-reference settlement rule

reading-reports.md said the cross-reference checks whether a profile's files appear in the platform config, a rule by name. Since 2026-10-10 declaration_settles counts a declaration only at the core's slot or at a size the core accepts, and an alias only where the core reads it.
---
 tests/test_doc_pages.py | 20 ++++++++++++++++++++
 wiki/reading-reports.md |  9 +++++++--
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/tests/test_doc_pages.py b/tests/test_doc_pages.py
index 516c7a5dc..fa33f91ee 100644
--- a/tests/test_doc_pages.py
+++ b/tests/test_doc_pages.py
@@ -1809,6 +1809,26 @@ class ClaimRuleNamesTheSizeProof(unittest.TestCase):
         self.assertIn("Two files of equal size are revisions", section)
 
 
+class CrossReferenceSettlesBySlotAndSize(unittest.TestCase):
+    """reading-reports.md said the cross-reference checks whether a profile's
+    files "appear in the platform config", a by-name rule, while verify
+    settles a file only at its slot or at a size the core accepts."""
+
+    def test_the_page_states_the_rule_verify_reads(self):
+        from validation import declaration_settles
+
+        rom1 = {"name": "ROM1.BIN", "size": 32768, "validation": ["size"]}
+        self.assertFalse(declaration_settles(rom1, "ROM1.BIN", {"ROM1.BIN": [(4096, "rom1.bin")]},
+                                             dest="dosbox/ROM1.BIN"))
+        self.assertTrue(declaration_settles(rom1, "ROM1.BIN", {"ROM1.BIN": [(32768, "rom1.bin")]},
+                                            dest="dosbox/ROM1.BIN"))
+        page = " ".join((ROOT / "wiki" / "reading-reports.md").read_text(encoding="utf-8").split())
+        section = page.split("### Cross-reference section", 1)[1].split("###", 1)[0]
+        self.assertIn("declaration_settles()", section)
+        self.assertIn("A name alone is not enough", section)
+        self.assertNotIn("appear in the platform config", section)
+
+
 class SkipFlagsNameTheSteps(unittest.TestCase):
     """--skip-packs said "add --skip-docs to stop after verify" while 4d and
     4e still ran, and the flag table left 8b out of --skip-docs."""
diff --git a/wiki/reading-reports.md b/wiki/reading-reports.md
index eda8e261f..8fa9d7fc2 100644
--- a/wiki/reading-reports.md
+++ b/wiki/reading-reports.md
@@ -140,8 +140,13 @@ are still included in packs automatically. A required one the collection lacks
 is listed under the counts, and `--verbose` lists the optional ones too.
 
 The cross-reference uses `resolve_platform_cores()` to determine which emulator
-profiles are relevant for each platform, then checks whether each profile's files
-appear in the platform config.
+profiles are relevant for each platform, then checks whether the platform
+already declares each profile's files (`declaration_settles()`). A name alone
+is not enough. The declaration must fill the core's own slot or have a size the
+core accepts: Galaksija's 4 KiB `ROM1.BIN` does not stand for DOSBox's 32 KiB
+SC-55 one. An alias counts only at the path where the core reads it, so
+RetroDECK's root `MSX.ROM` is not CLK's `MSX/MSX.ROM`. An archive counts by its
+name.
 
 ### Filtering output