Reading retopology quality out of triangle soup: meshcheck's TOP check family

What shipped

Phase 5 gives meshcheck a topology-quality vocabulary it did not have. Four new checks live in meshcheck-core: TOP-001 quad reconstructibility (share of triangles that pair cleanly back into quads), TOP-002 vertex valence regularity, TOP-003 triangle regularity / density chaos, and TOP-004 hard-edge share. glTF carries only triangles — quads and edge flow are authoring structure destroyed by export — so every TOP check reads a fingerprint of that structure out of the soup and reports a number. None accuses: all four ship info-severity, MAT-003 escalation params wired but dormant.

The load-bearing plumbing is a new shared weld.rs: a grid-hash tolerance weld (0.001, OnceLock-cached on Scene) that TOP-001/002/004 build adjacency on. CheckGroup::Top and Category::Topology are appended last so no existing report ordering moves.

The surface shipped behind the project’s first-ever schema minor bump: SCHEMA_VERSION 1.0 -> 1.1, additive only. SPEC_01 gained the TOP family section, SPEC_02 a dated 1.1 changelog, checks.toml four locked entries, the hand-authored openapi.json/llms.txt a hand-edited 1.1 + TOP, the MCP validate description a topology mention, and the site compare/checks/home pages the new rows. Every threshold traces to TOPO_CALIBRATION.md: the 21-asset distribution table (6 clean, 4 topo, 10 wild, 1 sanity) Ben locked from.

Decisions

The phase’s shape was set by research before code, and two proposal assumptions were wrong against source. TOP-004 was assumed to be “beveled-edge parity” with the Khronos Asset Auditor; reading Primitive.ts/EdgeXyz.ts showed the Auditor measures the angle between face normals, hard-codes >= π/2, counts edges with no length weighting, and welds by ~1e-5 rounding (A1). So TOP-004 matches that convention exactly and adds hard_edge_len_pct as a labeled improvement — the public wording holds “same 90° threshold and edge convention; we add length weighting”, never “same metric”. TOP-001’s shape limit was assumed to be an aspect/skew ratio; Blender’s bmo_join_triangles.cc uses max corner-angle deviation from 90° scored by a 3-term quad_calc_error (A2), so quad_shape_max became quad_shape_deg, with a total-order tie-break (A3, a required determinism divergence from Blender’s tie-break-free heap).

D6 kept every threshold provisional until M1 measured real corpora; the locks Ben set (frontmatter) are calibration outputs, not guesses copied from Blender. A4 forced the weld extraction: GEO-005’s grid-hash was private inline code and GeometryKit welds exact-bitwise, so weld.rs is new.

What broke

The M1 review caught a scoring bug that claimed source fidelity it did not have: the Blender error normalization was implemented as 1 - cos with the shape term overweighted 4x, rather than angle / 2π. The fix moved only Duck-family sweep cells (max +0.81); anchor assets were unchanged. The round-2 report then understated its own change (Duck moved +0.28 at the recommended cell); the artifact was verified internally consistent instead.

The weld basis was the second M1 catch. Exact-bitwise welding understated hard edges on any mesh with near-duplicate positions: Duck__unweld reported 0 hard edges exact vs 46 tolerance-welded (tracking clean Duck’s 47), and 5 of 10 wild assets were understated — the long sword went 0.14% -> 3.28% between bases. A weld-basis comparison table surfaced this and drove Ben’s tolerance-weld lock for TOP-004.

Two more. The soup fixture, specced as marching-cubes, became marching-tetrahedra (no ambiguous-case tables, same smooth iso-surface). And Blob__mc_soup did not land near zero — it scores 29.3% quad-reconstructible at the locked pair, because a smooth iso-surface is locally planar and partially reconstructs; the shape delimiter carries the discrimination, not planarity, and it still separates cleanly from the 100% authored torus.

In M2, the schema was out of scope but Category::Topology needed to serialize, so the JsonSchema derive was hand-frozen at the 1.0 eight-variant enum — “topology” appeared in reports but not in docs/schema/, an accepted deviation with an explicit M3 obligation. M3 discharged it: the derive restored (nine variants), docs/schema/ re-emitted, the drift being exactly the additive enum value.

Numbers

The gating measurements held across M2 and M3. checks_only p95 with TOP enabled came in at 76 ms (<=50k tris) and 549 ms (<=500k tris), inside the Phase 0 gates of 500 ms and 3 s. wasm-vs-native parity was 32/32 byte-identical including the topo fixtures; the determinism double-run showed 0 diffs. A negative proof backed the bench: tampering the Blob quad_pct band 35 -> 20 made the gate exit 1, and a deterministic regenerate restored the green gate.

The M4 sweep pushed all 10 wild GLBs through the deployed preview /validate with TOP enabled — two small assets sync, the eight large ones (20.6-56.7 MB) via the presigned-upload + async-job path. All returned HTTP 200, schema_version 1.1, four TOP results at status pass. Every number reproduced the M1 calibration: TOP-002/003 to the decimal, TOP-004 the locked tolerance-weld (tol) columns exactly (long sword 39,856 hard edges / 3.28%), TOP-001 within 0.05 on all 10 — retopologized output at 56-70%, dense scans at 13-34%. The lone non-exact match was war pig’s TOP-001: core 69.73% vs the throwaway prototype’s 69.69%, a 0.04-point tie-break difference between two independent greedy implementations — the core value is deterministic (double-run and wasm parity byte-identical) and the four gated fixtures matched the prototype exactly.

Next

Phase 5 closes on the M4 wild-corpus sweep and the reviewer’s phase-5 tag; the branch merges into the Phase 4 launch soak. The remaining v1.1 topology work — an authoring profile that promotes TOP checks to warning via the dormant escalation params — is out of scope here. Next up is the launch soak’s own gates: the 48-hour staging run and the registry submissions that unblock the npx meshcheck-mcp story.