Box dimensions: enrich learns shelf math, dims reports the Kallax truth

Eric's brief, implemented to the letter. BGG keeps physical dimensions
on VERSIONS, not games, so enrich runs a second cached pass over
thing?versions=1 (same batching, token, rate limit, and cache as every
call). A game with a chosen version takes that exact version's numbers
(source "version", mirrored onto its version dict); a versionless game
gets numbers only when every printing with data agrees within 0.5" per
axis (source "unanimous", keeping the MAX per axis — the planning
question is "will it fit"); disagreement stores nulls as "conflicting"
— never a guess — and BGG's 0 parses as "never entered", not a real
dimension. rpgitems and local games are "absent". Read-only: upload
untouched.

The new offline `bggpipe dims` reports coverage by source, the ten
biggest footprints, and a Kallax fit check (13.2" square opening,
15.4" deep; a box fits if SOME orientation puts two axes through the
opening within the depth) — naming every misfit and every game whose
dimensions can't be verified, because can't-verify ≠ fits. Trusted
numbers surface on the Library detail page as a "box" row.

First real run: 54 version-exact, 16 unanimous, 39 conflicting, 27
absent; three genuine misfits (Bugs in the Kitchen's 17" box, History
of the World and Risk LotR both over the 15.4" depth).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016jXZFSTZQKzAC8fqpWSz9g

tests/test_enrich.py

@@ -151,11 +151,25 @@ def _cfg_with_matches(tmp_path):
 
 
 def _seed_batch_fixture(cache_dir):
-    """The batch cache entry run_enrich will ask for: sorted ids 13,266192."""
+    """The cache entries run_enrich will ask for: the stats batch and the
+    dims pass's versions batch (sorted ids 13,266192)."""
     cache_dir.mkdir(parents=True, exist_ok=True)
     combined = FULL_THING_XML.replace("<items>", "<items>" + CATAN_MINIMAL[7:-8], 1)
     key = cache_key("thing", {"id": "13,266192", "stats": "1"})
     (cache_dir / key).write_text(combined)
+    versions_key = cache_key("thing", {"id": "13,266192", "versions": "1"})
+    (cache_dir / versions_key).write_text(
+        """<items>
+          <item type="boardgame" id="13"><versions>
+            <item type="boardgameversion" id="7"><width value="9.5" />
+              <length value="11.5" /><depth value="3" /><weight value="3" /></item>
+          </versions></item>
+          <item type="boardgame" id="266192"><versions>
+            <item type="boardgameversion" id="465063"><width value="11.7" />
+              <length value="11.7" /><depth value="2.8" /><weight value="4.4" /></item>
+          </versions></item>
+        </items>"""
+    )
 
 
 def test_run_enrich_writes_games_json_with_versions(tmp_path):
@@ -209,7 +223,9 @@ def test_refresh_bypasses_cache_read(tmp_path):
 
     client = BGGClient(cache_dir=cache, transport=httpx.MockTransport(handler))
     games = run_enrich(cfg, refresh=True, client=client)
-    assert len(requests) == 1  # cache read skipped, live fetch happened
+    # cache reads skipped, live fetches happened: stats batch + dims pass
+    assert any("stats=1" in u for u in requests)
+    assert any("versions=1" in u for u in requests)
     assert games["266192:465063"]["rating"] == 7.5
 
 
@@ -338,3 +354,109 @@ def test_corrupt_local_games_store_fails_loud(tmp_path):
     )
     with pytest.raises(ValueError, match="local_games.json is corrupt"):
         run_enrich(cfg, client=bare)
+
+
+DIMS_XML = """<items>
+  <item type="boardgame" id="240">
+    <versions>
+      <item type="boardgameversion" id="24621">
+        <width value="8.4" /><length value="11.5" /><depth value="2.1" />
+        <weight value="2" />
+      </item>
+      <item type="boardgameversion" id="99999">
+        <width value="0" /><length value="0" /><depth value="0" />
+        <weight value="0" />
+      </item>
+    </versions>
+  </item>
+  <item type="boardgame" id="500">
+    <versions>
+      <item type="boardgameversion" id="1"><width value="11.6" />
+        <length value="11.6" /><depth value="2.8" /><weight value="4.1" /></item>
+      <item type="boardgameversion" id="2"><width value="11.8" />
+        <length value="11.4" /><depth value="3.0" /><weight value="4.3" /></item>
+      <item type="boardgameversion" id="3"><width value="0" />
+        <length value="0" /><depth value="0" /><weight value="0" /></item>
+    </versions>
+  </item>
+  <item type="boardgame" id="600">
+    <versions>
+      <item type="boardgameversion" id="4"><width value="8.0" />
+        <length value="8.0" /><depth value="2.0" /><weight value="1" /></item>
+      <item type="boardgameversion" id="5"><width value="12.0" />
+        <length value="12.0" /><depth value="3.0" /><weight value="5" /></item>
+    </versions>
+  </item>
+  <item type="boardgame" id="700">
+    <versions>
+      <item type="boardgameversion" id="6"><width value="16.2" />
+        <length value="16.2" /><depth value="4.0" /><weight value="7" /></item>
+    </versions>
+  </item>
+</items>"""
+
+
+def test_parse_version_dims_treats_zero_as_absent():
+    from bggpipe.models import parse_version_dims
+
+    by_game = parse_version_dims(DIMS_XML)
+    exact = next(r for r in by_game[240] if r["version_id"] == 24621)
+    assert exact["width_in"] == 8.4 and exact["weight_lb"] == 2
+    zeroed = next(r for r in by_game[240] if r["version_id"] == 99999)
+    assert all(
+        zeroed[f] is None for f in ("width_in", "length_in", "depth_in", "weight_lb")
+    )
+
+
+def test_entry_dims_verdicts():
+    """The four sources: exact version, unanimous chorus (within 0.5"),
+    conflicting chorus (nulls, never a guess), and absent."""
+    from bggpipe.enrich import _entry_dims
+    from bggpipe.models import parse_version_dims
+
+    by_game = parse_version_dims(DIMS_XML)
+
+    versioned = _entry_dims({"version": {"version_id": 24621}}, by_game[240])
+    assert versioned["source"] == "version" and versioned["width_in"] == 8.4
+
+    # chosen version exists but carries only zeros: absent, not borrowed
+    zeroed = _entry_dims({"version": {"version_id": 99999}}, by_game[240])
+    assert zeroed["source"] == "absent" and zeroed["width_in"] is None
+
+    unanimous = _entry_dims({"version": None}, by_game[500])
+    assert unanimous["source"] == "unanimous"
+    assert unanimous["width_in"] == 11.8  # max per axis: the fit question
+    assert unanimous["depth_in"] == 3.0
+
+    conflicting = _entry_dims({"version": None}, by_game[600])
+    assert conflicting["source"] == "conflicting"
+    assert conflicting["width_in"] is None
+
+    assert _entry_dims({"version": None}, [])["source"] == "absent"
+
+
+def test_enrich_fills_dims_from_cached_versions(tmp_path):
+    from bggpipe.enrich import run_enrich
+
+    cfg = _cfg_with_matches(tmp_path)
+    cache = tmp_path / "cache"
+    _seed_batch_fixture(cache)
+    (cache / cache_key("thing", {"id": "13,266192", "versions": "1"})).write_text(
+        """<items>
+          <item type="boardgame" id="13"><versions>
+            <item type="boardgameversion" id="7"><width value="11.6" />
+              <length value="11.6" /><depth value="3.0" /><weight value="4" /></item>
+          </versions></item>
+          <item type="boardgame" id="266192"><versions>
+            <item type="boardgameversion" id="465063"><width value="11.7" />
+              <length value="11.7" /><depth value="2.8" /><weight value="4.4" /></item>
+          </versions></item>
+        </items>"""
+    )
+    client = BGGClient(cache_dir=cache, transport=httpx.MockTransport(_no_network))
+    games = run_enrich(cfg, client=client)
+    wingspan = games["266192:465063"]
+    assert wingspan["dims"]["source"] == "version"
+    assert wingspan["dims"]["depth_in"] == 2.8
+    assert wingspan["version"]["width_in"] == 11.7  # mirrored onto the version
+    assert games["13"]["dims"]["source"] == "unanimous"