fix(showcase): hay-bale quality pass with five new hygiene budgets, and exit-pre-sidecar doc accuracy

[TMHSDigital]

Quality pass over two items: one showcase piece (Track A) and one
pathology example (Track C).

Binaries — all local, exact paths and self-reported versions:
.scratch/blender-4.5.11-windows-x64/blender.exe → Blender 4.5.11 LTS ·
.scratch/blender-5.1.2-windows-x64/blender.exe → Blender 5.1.2 ·
.scratch/5.2/blender-5.2.1-windows-x64/blender.exe → Blender 5.2.1 LTS

---

1. showcase/hay-bale — Track A

Never had a visual quality pass (last touched by #170, a rebuild).
Inspection sheet: 18 renders at 1200 px in .scratch/qp2/hay-bale-r1/
(six orthos, two three-quarters, clay, wireframe overlay, seven joint
close-ups, ground contact), all opened and looked at. Four rounds.

Defects found, and the view that revealed each

#	Part	Defect	Revealed by
1	twine belts	Constant-size rectangles on a rounded, bulged loaf: proud at the middle of each face, swallowed at the corners, and vanishing into the loaf 2.9–8.3 mm above the floor instead of wrapping under	ortho_bottom (bottom face bare, only two stub ends), ground_contact (belt terminates in mid-air), shell probe zmin=+0.00832 / +0.00294 vs loaf 0.00000
2	belts + loops	The two belts 5.4 mm out of step; loop shells likewise. Cause: ridge term sin(x*24) is odd in x, so the stations sampled different surface heights	shell probe; ortho_top (loop nubs at different heights)
3	loaf	Nothing cinched — 0.2498 m at the belt vs 0.2585 m mid-span, and the ends (0.2469) narrower than the belt station	ortho_front, ortho_top, cinch profile probe
4	whole mesh	426/426 faces smooth-shaded — erased every ridge and nap; read as a bar of soap	clay_three_quarter, three_quarter_a
5	loaf ends	No end nap despite the README claiming one	ortho_left
6	long faces	Ridge amplitude 7 mm on a 0.9 m subject — below the visible threshold	all orthos
7	hitch loops	Read as machined rivet heads, not knots	ortho_top, wire_three_quarter
8	belt section	Razor-edged flat ribbon, reads as masking tape	joint_belt0_side
9	loaf bottom	Convex base domed down then clamped flat by if v.co.z < 0: v.co.z = 0	ortho_bottom shading gradient

Fixes, and why each is structural

• Build, bevel and ground the loaf first, then hang the belts. Each
  belt raycasts the finished cross-section at its own station
  (loaf_profile) and follows it at a named bite. Placing belts against
  half-built geometry and shifting everything afterwards is what left
  each one a different distance off the floor. Moving a belt now moves
  its seat with it. (1, 2, 8)
• Every shaping term is even in x — cos, not sin. An odd term
  cannot produce mirrored members. (2)
• The cinch is derived from BELT_XS, and the ridge fades out under
  each belt because twine compresses straw flat where it bites. Without
  that fade the ±14 mm ridge swamped the waist. (3, 6)
• Shading decided per part: flat loaf (straw is a chunky matte
  mass), smooth cord. (4)
• Straw detail moved to the high mesh — the bake stage already
  exists to carry it. A low mesh dense enough to model flakes directly
  would cost thousands of triangles. (5)
• Gravity flattens the contact face via a grounded falloff, instead
  of doming down and being clamped. (9)
• Nap damped to nothing at the face border (the bevel runs after it, and
  displacing border verts flared the corners into spikes) and keyed to
  Z strata, not radial rings — the ring form resolved at BAKE_RES
  into a pixelated bullseye on the hero.

New hygiene budgets — all recomputed from the generated mesh

Budget	Exit	Declared	Measured (4.5.11 / 5.1.2 / 5.2.1)
Cross-shell coplanar z-fight pairs	15	0	0 / 0 / 0
Per-belt wrap zmin	16	≤ 0.006 m	0.002628 both belts, all three
Shell count	17	exactly 5	5 / 5 / 5
Banded belt seat depth	18	every station in [0.002, 0.020] m	0.00400–0.01676 over 20/20 stations, both belts, all three
Belt mirror symmetry	19	≤ 5e-4 m	0.000000 / 0.000000 / 0.000000
Cinch depth	19	[0.006, 0.020] m	0.01420 on all three
Loaf X × Z	19	(0.922, 0.409) ± 0.02	(0.9208, 0.4087) on all three

The z-fight count is cross-shell, not merely share-no-vertex: two
quads two steps apart on one flat cap share no vertex and are coplanar
by construction, which read 96 pairs, none of them a hazard.

Exit codes — default and every falsifier, all three binaries

Run	4.5.11	5.1.2	5.2.1	Target budget
default	0	0	0	—
--skip-decimate	9	9	9	LOD1 ratio band
--stray-vert (new)	15	15	15	hygiene: loose vertices
--lift-z	16	16	16	grounded AABB zmin
--float-belts (new)	16	16	16	per-belt wrap zmin
--slack-belt (new)	18	18	18	banded seat depth
--skew-belt (new)	19	19	19	belt mirror symmetry

Two falsifiers were re-aimed rather than widening anything:
--stray-vert parked its vertex above the bale and tripped the bbox
budget (8) first, proving nothing about hygiene — it now sits inside.
--skew-belt used a Z shift that landed a belt face coplanar with a
loaf face and tripped z-fight (15) — it now shifts along X, where the
loaf profile barely changes so every other budget stays green.
tests/check_falsifier_targets.py passes: 166 falsifiers, 26 pieces.

Triangles and determinism

Base 852 → 2012 tris (band widened 750–1100 → 1700–2400; showcase
budgets are meant to grow). Collider 78 → 156, ceiling 400 unchanged.
Every geometric figure is identical on all three binaries; only the
glTF export differs, by 8 B on 5.2.1, which is not a gated axis.

Hero and gates

Framing gate passes, check_framing called with no deviation=:
fill x=0.575 y=0.789 band=0.70..0.90, margins 0.237 / 0.188 / 0.106 / 0.106, no edge touch. Camera moved from 50 mm at 2.1 m to 70 mm
further back (a 0.92 m subject had the near end reading half again as
large as the far one) and the yaw from −32° to −20° so the long ribbed
flank reads rather than the end.

Contact sheet: docs/gallery/contact-sheets/hay-bale-contact-sheet.webp,
against the pinned set (armature-bend, damped-track-aim,
bmesh-gear).

Criterion	Verdict
Stage darkness	Pass — mean luminance 75.6 inside the calibration band 44.5–77.7; dark fraction 0.196
Wedge warmth	Pass after a fix. The first sheet read as a neutral grey stage against three peers that all carry a warm pool — pulling the lens back had left the wedge falling outside frame. Light brought in and down; re-shot.
Subject fill	Pass — 0.789, comparable to bmesh-gear
Saturation	Pass — 0.242 vs band 0.150–0.248
Thumbnail legibility	Fail as a hay bale. At card size it reads as a cardboard carton or an olive ammo crate.

Stopping honestly

Four inspection rounds; past the three-round limit. Form, binding and
hygiene are right and locked; the surface is not — it still reads as
a wrapped parcel, not straw. That is a material and bake problem, not a
geometry one: straw needs directional fibre and colour break-up that a
256 px tangent-space normal off a smooth high mesh cannot deliver.
Recorded in the piece README under Known gap so the next run does
not re-litigate the silhouette. The stale still was re-rendered because
the geometry changed and leaving it would misrepresent the asset.

Incidental

The piece deleted no temp export, and Blender's TMPDIR resolves to the
working directory on a portable build, so every run left a .glb in the
repo root (39 accumulated during this pass). Fixed here; the same
pattern is in all 28 showcase pieces and is left for a follow-up
rather than touched in a quality-pass PR.

---

2. examples/exit-pre-sidecar — Track C

Contract frozen. Documentation only.

Correctness bug found in the docs, not the contract. The module
docstring read "Catalog min_version 5.0 is wrong — the floor is
5.1." The catalog has carried min_version: 5.1 since the example's
introducing commit (bb5a2df), so the note was never true and would
send a reader to "fix" a correct row. Removed.

Re-verification against all three binaries. The documented behaviour
is correct: hasattr(bpy.app.handlers, "exit_pre") is False on
4.5.11 LTS, True on 5.1.2 and 5.2.1 LTS — and exit_pre is the only
exit- or quit-related name in bpy.app.handlers on the versions that
have it, so there is no older spelling to fall back to.

README improvements: states the contract and the bug class it
catches (atexit for teardown work); adds the 4.5 and 5.2
bpy.app.handlers API links, noting the 4.5 page lists no exit_pre;
explains that exiting 77 on 4.5 is correct by design and what stops
a skip spreading (min_version 5.1, the runner failing a skip above the
floor, summarize.py reddening an all-skip job); and enumerates the
falsifiers in a table with what each breaks, its script exit and how the
harness fails — naming --write-in-main and --atexit-instead as the
two an existence-only check would pass, which is why the catalog row
carries sidecar_contains.

Contract, assertions and exit codes unchanged. Identical before and
after:

Run	4.5.11	5.1.2	5.2.1
default (harness)	SKIP	PASS	PASS
--silent-handler	—	—	harness FAIL
--no-handler	—	—	harness FAIL
--wrong-text	—	harness FAIL	harness FAIL
--write-in-main	—	—	harness FAIL
--atexit-instead	—	harness FAIL	harness FAIL
--force-run (script)	2	—	—
default (script)	77	—	—

---

3. showcase/README.md conventions

Three conventions every future piece inherits, each from a defect above
that no existing budget could see: even shaping terms and mirror
symmetry (19); wrappers follow the host's profile, and the host is
finished first (16/18), including per-wrapper-shell grounding because
the AABB gate stays green when the host grounds the box; and
station-local seat measurement — never nearest-surface distance in a
concave waist, and bin by rounding, never flooring, or a station on a
bin boundary splits its inner and outer rings. Plus the cross-shell
sharpening of the z-fight budget.

---

Proven by live run vs. inspection

Live run on all three binaries: every exit code, every measured
budget figure, the version claims in §2, the framing gate, determinism
across versions, and the temp-export cleanup. Inspection only: the
contact-sheet verdicts are my judgement of the committed composite, and
the "reads as a parcel" verdict in §1 is a judgement call, not a
measurement.

Inspection renders stay in .scratch/, which is gitignored.

🤖 Generated with Claude Code