fix(showcase): one canonical convex_hull_collider and export_unity; report helper drift

Showcase helpers are copied inline by design, but nothing tied the copies
together. convex_hull_collider existed in 10 variants: the is_valid guard on
geom_interior/geom_unused (a hull can list an element in both; deleting it
twice raises ReferenceError) had reached 14 copies while 39 kept the
unguarded body. export_unity had 3 equivalent variants.

- Every plain collider copy (54 pieces) now carries one canonical guarded
  body with a comment saying why. Three variants stay, each now guarded and
  recorded as justified: dissolve + triangulate for round props (anvil,
  campfire, wooden-barrel, wooden-bucket), hull from bare vertices
  (farm-tractor), per-group hulls (sea-stack-arch).
- export_unity: one body in all 76 pieces.
- tests/check_helper_drift.py hashes each copy of the named pipeline helpers
  (docstrings ignored) and compares the variant count with the allowance and
  reason recorded in its CANONICAL table; --show NAME prints each variant,
  --strict fails. Validate runs it warn-only. Current: collider 4/4,
  export_unity 1/1, hygiene_audit 7/7, pack_uvs 13/13, assign_slots 20/20.
- showcase/README.md: "Canonical helpers" says which body to copy and how to
  rerun the report.

Proof (local, .scratch/blender-5.2.1-windows-x64, 5.2.1 LTS): run_catalog over
all 76 showcase rows after the change: 76 happy paths PASS and 76 catalog
falsifiers PASS at their declared exits (152/152), so every collider budget,
triangle ceiling and export still holds. Every script py_compiles.

Closes #344

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: TMHSDigital

.github/workflows/validate.yml

@@ -73,6 +73,9 @@ jobs:
       - name: Every gallery still is gated by gallery_framing
         run: python3 tests/check_render_gates.py
 
+      - name: Showcase helper drift (warn-only report)
+        run: python3 tests/check_helper_drift.py
+
       - name: Check falsifiers declare the budget they target
         run: python3 tests/check_falsifier_targets.py
 

showcase/README.md

@@ -743,6 +743,18 @@ entry in `showcase/gallery.json`, and a rendered still.
   piece composes. Duplicated helpers stay inlined or copied; showcase
   scripts do not import snippets as a package.
 
+- **Canonical helpers.** Copy a pipeline helper from a piece that carries
+  the canonical body, not from whichever piece is nearest.
+  `tests/check_helper_drift.py` (Validate, warn-only) hashes each copy and
+  lists outliers; its `CANONICAL` table is the record of how many variants
+  each helper may have and why. `convex_hull_collider` has one guarded
+  body (filter `geom_interior` / `geom_unused` on `is_valid` before each
+  delete; the hull can list an element twice) plus three justified
+  variants: dissolve + triangulate for round props, hull from bare
+  vertices (`farm-tractor`), per-group hulls (`sea-stack-arch`).
+  `export_unity` has exactly one body. Fix a helper bug in every copy, then
+  rerun the report: `python tests/check_helper_drift.py --show NAME`.
+
 ## Layout
 
 ```text

showcase/anvil/anvil.py

@@ -1162,24 +1162,24 @@ def make_lod(obj, name, ratio, skip_decimate):
 
 
 def convex_hull_collider(obj, name):
+    # bmesh.ops.convex_hull can list the same element in geom_interior and
+    # geom_unused; once deleted it is invalid and a second delete raises
+    # ReferenceError. Filter on is_valid before each delete.
+    # Variant for round props: limited dissolve merges the hull's near-coplanar
+    # facets, then triangulate, to stay under the collider triangle ceiling.
     mesh = bpy.data.meshes.new(name)
     bm = bmesh.new()
     try:
         bm.from_mesh(obj.data)
         result = bmesh.ops.convex_hull(bm, input=list(bm.verts))
-        interior = result.get("geom_interior") or []
-        unused = result.get("geom_unused") or []
+        interior = [g for g in result.get("geom_interior") or [] if g.is_valid]
         if interior:
             bmesh.ops.delete(bm, geom=interior, context="VERTS")
+        unused = [g for g in result.get("geom_unused") or [] if g.is_valid]
         if unused:
             bmesh.ops.delete(bm, geom=unused, context="VERTS")
-        bmesh.ops.dissolve_limit(
-            bm,
-            angle_limit=math.radians(10.0),
-            verts=list(bm.verts),
-            edges=list(bm.edges),
-            delimit={"NORMAL"},
-        )
+        bmesh.ops.dissolve_limit(bm, angle_limit=math.radians(10.0), verts=list(bm.verts),
+                                 edges=list(bm.edges), delimit={"NORMAL"})
         bmesh.ops.triangulate(bm, faces=list(bm.faces))
         bm.to_mesh(mesh)
         mesh.update()
@@ -1235,14 +1235,9 @@ def export_unity(path, objects):
     for ob in objects:
         ob.select_set(True)
     bpy.context.view_layer.objects.active = objects[0]
-    bpy.ops.export_scene.gltf(
-        filepath=path,
-        use_selection=True,
-        export_yup=True,
-        export_apply=True,
-        export_draco_mesh_compression_enable=False,
-        export_animations=False,
-    )
+    bpy.ops.export_scene.gltf(filepath=path, use_selection=True, export_yup=True,
+                              export_apply=True, export_draco_mesh_compression_enable=False,
+                              export_animations=False)
 
 
 def check(

showcase/apothecary-shelf/apothecary_shelf.py

@@ -1305,10 +1305,9 @@ def export_unity(path, objects):
     for ob in objects:
         ob.select_set(True)
     bpy.context.view_layer.objects.active = objects[0]
-    bpy.ops.export_scene.gltf(
-        filepath=path, use_selection=True, export_yup=True, export_apply=True,
-        export_draco_mesh_compression_enable=False, export_animations=False,
-    )
+    bpy.ops.export_scene.gltf(filepath=path, use_selection=True, export_yup=True,
+                              export_apply=True, export_draco_mesh_compression_enable=False,
+                              export_animations=False)
 
 
 def check(skip_decimate, lift_z=False, **flags):

showcase/archery-target/archery_target.py

@@ -2124,16 +2124,18 @@ def make_lod(obj, name, ratio, skip_decimate):
 
 
 def convex_hull_collider(obj, name):
-    # Duplicated from snippets/convex_hull_collider.py (not a package).
+    # bmesh.ops.convex_hull can list the same element in geom_interior and
+    # geom_unused; once deleted it is invalid and a second delete raises
+    # ReferenceError. Filter on is_valid before each delete.
     mesh = bpy.data.meshes.new(name)
     bm = bmesh.new()
     try:
         bm.from_mesh(obj.data)
         result = bmesh.ops.convex_hull(bm, input=list(bm.verts))
-        interior = result.get("geom_interior") or []
-        unused = result.get("geom_unused") or []
+        interior = [g for g in result.get("geom_interior") or [] if g.is_valid]
         if interior:
             bmesh.ops.delete(bm, geom=interior, context="VERTS")
+        unused = [g for g in result.get("geom_unused") or [] if g.is_valid]
         if unused:
             bmesh.ops.delete(bm, geom=unused, context="VERTS")
         bm.to_mesh(mesh)
@@ -2187,20 +2189,14 @@ def bake_normal(high, low):
 
 
 def export_unity(path, objects):
-    # Duplicated from snippets/export_preset_unity.py (not a package).
     for ob in bpy.context.view_layer.objects:
         ob.select_set(False)
     for ob in objects:
         ob.select_set(True)
     bpy.context.view_layer.objects.active = objects[0]
-    bpy.ops.export_scene.gltf(
-        filepath=path,
-        use_selection=True,
-        export_yup=True,
-        export_apply=True,
-        export_draco_mesh_compression_enable=False,
-        export_animations=False,
-    )
+    bpy.ops.export_scene.gltf(filepath=path, use_selection=True, export_yup=True,
+                              export_apply=True, export_draco_mesh_compression_enable=False,
+                              export_animations=False)
 
 
 FLOOR_NAMES = ("straw", "twine", "timber", "steel", "white", "black", "blue", "red", "gold",

showcase/bamboo-clump/bamboo_clump.py

@@ -1578,17 +1578,18 @@ def make_lod(obj, name, ratio, skip_decimate):
 
 
 def convex_hull_collider(obj, name):
-    # Duplicated from snippets/convex_hull_collider.py (not a package).
+    # bmesh.ops.convex_hull can list the same element in geom_interior and
+    # geom_unused; once deleted it is invalid and a second delete raises
+    # ReferenceError. Filter on is_valid before each delete.
     mesh = bpy.data.meshes.new(name)
     bm = bmesh.new()
     try:
         bm.from_mesh(obj.data)
         result = bmesh.ops.convex_hull(bm, input=list(bm.verts))
-        interior = result.get("geom_interior") or []
-        unused = result.get("geom_unused") or []
+        interior = [g for g in result.get("geom_interior") or [] if g.is_valid]
         if interior:
             bmesh.ops.delete(bm, geom=interior, context="VERTS")
-        unused = [v for v in unused if v.is_valid]
+        unused = [g for g in result.get("geom_unused") or [] if g.is_valid]
         if unused:
             bmesh.ops.delete(bm, geom=unused, context="VERTS")
         bm.to_mesh(mesh)
@@ -1642,20 +1643,14 @@ def bake_normal(high, low):
 
 
 def export_unity(path, objects):
-    # Duplicated from snippets/export_preset_unity.py (not a package).
     for ob in bpy.context.view_layer.objects:
         ob.select_set(False)
     for ob in objects:
         ob.select_set(True)
     bpy.context.view_layer.objects.active = objects[0]
-    bpy.ops.export_scene.gltf(
-        filepath=path,
-        use_selection=True,
-        export_yup=True,
-        export_apply=True,
-        export_draco_mesh_compression_enable=False,
-        export_animations=False,
-    )
+    bpy.ops.export_scene.gltf(filepath=path, use_selection=True, export_yup=True,
+                              export_apply=True, export_draco_mesh_compression_enable=False,
+                              export_animations=False)
 
 
 

showcase/basketball-hoop/basketball_hoop.py

@@ -1637,16 +1637,18 @@ def make_lod(obj, name, ratio, skip_decimate):
 
 
 def convex_hull_collider(obj, name):
-    # Duplicated from snippets/convex_hull_collider.py (not a package).
+    # bmesh.ops.convex_hull can list the same element in geom_interior and
+    # geom_unused; once deleted it is invalid and a second delete raises
+    # ReferenceError. Filter on is_valid before each delete.
     mesh = bpy.data.meshes.new(name)
     bm = bmesh.new()
     try:
         bm.from_mesh(obj.data)
         result = bmesh.ops.convex_hull(bm, input=list(bm.verts))
-        interior = result.get("geom_interior") or []
-        unused = result.get("geom_unused") or []
+        interior = [g for g in result.get("geom_interior") or [] if g.is_valid]
         if interior:
             bmesh.ops.delete(bm, geom=interior, context="VERTS")
+        unused = [g for g in result.get("geom_unused") or [] if g.is_valid]
         if unused:
             bmesh.ops.delete(bm, geom=unused, context="VERTS")
         bm.to_mesh(mesh)
@@ -1700,20 +1702,14 @@ def bake_normal(high, low):
 
 
 def export_unity(path, objects):
-    # Duplicated from snippets/export_preset_unity.py (not a package).
     for ob in bpy.context.view_layer.objects:
         ob.select_set(False)
     for ob in objects:
         ob.select_set(True)
     bpy.context.view_layer.objects.active = objects[0]
-    bpy.ops.export_scene.gltf(
-        filepath=path,
-        use_selection=True,
-        export_yup=True,
-        export_apply=True,
-        export_draco_mesh_compression_enable=False,
-        export_animations=False,
-    )
+    bpy.ops.export_scene.gltf(filepath=path, use_selection=True, export_yup=True,
+                              export_apply=True, export_draco_mesh_compression_enable=False,
+                              export_animations=False)
 
 
 def check(skip_decimate, lift_z=False, stray_vert=False, short_brace=False,

showcase/book-trolley/book_trolley.py

@@ -1474,10 +1474,9 @@ def export_unity(path, objects):
     for ob in objects:
         ob.select_set(True)
     bpy.context.view_layer.objects.active = objects[0]
-    bpy.ops.export_scene.gltf(
-        filepath=path, use_selection=True, export_yup=True, export_apply=True,
-        export_draco_mesh_compression_enable=False, export_animations=False,
-    )
+    bpy.ops.export_scene.gltf(filepath=path, use_selection=True, export_yup=True,
+                              export_apply=True, export_draco_mesh_compression_enable=False,
+                              export_animations=False)
 
 
 def check(skip_decimate, lift_z=False, **flags):

showcase/bookshelf/bookshelf.py

@@ -1376,10 +1376,9 @@ def export_unity(path, objects):
     for ob in objects:
         ob.select_set(True)
     bpy.context.view_layer.objects.active = objects[0]
-    bpy.ops.export_scene.gltf(
-        filepath=path, use_selection=True, export_yup=True, export_apply=True,
-        export_draco_mesh_compression_enable=False, export_animations=False,
-    )
+    bpy.ops.export_scene.gltf(filepath=path, use_selection=True, export_yup=True,
+                              export_apply=True, export_draco_mesh_compression_enable=False,
+                              export_animations=False)
 
 
 def check(skip_decimate, lift_z=False, **flags):

showcase/boulder-cluster/boulder_cluster.py

@@ -1915,18 +1915,18 @@ def make_lod(obj, name, ratio, skip_decimate):
 
 
 def convex_hull_collider(obj, name):
-    # Duplicated from snippets/convex_hull_collider.py (not a package).
+    # bmesh.ops.convex_hull can list the same element in geom_interior and
+    # geom_unused; once deleted it is invalid and a second delete raises
+    # ReferenceError. Filter on is_valid before each delete.
     mesh = bpy.data.meshes.new(name)
     bm = bmesh.new()
     try:
         bm.from_mesh(obj.data)
         result = bmesh.ops.convex_hull(bm, input=list(bm.verts))
-        interior = result.get("geom_interior") or []
-        unused = result.get("geom_unused") or []
+        interior = [g for g in result.get("geom_interior") or [] if g.is_valid]
         if interior:
             bmesh.ops.delete(bm, geom=interior, context="VERTS")
-        # the source is a point cloud: a vertex can be both interior and unused
-        unused = [v for v in unused if v.is_valid]
+        unused = [g for g in result.get("geom_unused") or [] if g.is_valid]
         if unused:
             bmesh.ops.delete(bm, geom=unused, context="VERTS")
         bm.to_mesh(mesh)
@@ -1980,20 +1980,14 @@ def bake_normal(high, low):
 
 
 def export_unity(path, objects):
-    # Duplicated from snippets/export_preset_unity.py (not a package).
     for ob in bpy.context.view_layer.objects:
         ob.select_set(False)
     for ob in objects:
         ob.select_set(True)
     bpy.context.view_layer.objects.active = objects[0]
-    bpy.ops.export_scene.gltf(
-        filepath=path,
-        use_selection=True,
-        export_yup=True,
-        export_apply=True,
-        export_draco_mesh_compression_enable=False,
-        export_animations=False,
-    )
+    bpy.ops.export_scene.gltf(filepath=path, use_selection=True, export_yup=True,
+                              export_apply=True, export_draco_mesh_compression_enable=False,
+                              export_animations=False)
 
 
 def check(skip_decimate, lift_z=False, stray_vert=False, perch_boulder=False, float_slab=False,